HELP — VMS 5.5
Additional information available:
:==@ACCOUNTINGALLOCATEANALYZE
APPENDASSIGNATTACHAUTHORIZEAUTOGENBACKUP
CALLCANCELCLOSECONNECTCONTINUECONVERTCOPY
CREATEDEALLOCATEDEASSIGNDEBUGDECKDEFINE
DELETEDEPOSITDIFFERENCESDIRECTORYDISABLE
DISCONNECTDISKQUOTADISMOUNTDUMPEDIT
ENABLEEODEOJEXAMINEEXCHANGEEXITFDL
FONTGOSUBGOTOHELPIFINITIALIZEINQUIRE
INSTALLJOBLATCPLIBRARYLICENSELINKLMCP
LOGINLOGOUTMACROMAILMERGEMESSAGEMONITOR
MOUNTNCPNCSONOPENPASSWORDPATCH
PHONEPRINTPSWRAPPURGEREADRECALLRECOVER
RENAMEREPLYREQUESTRETURNRMSRUNRUNOFF
SEARCHSETSHOWSORTSPAWNSTARTSTOP
SUBMITSYNCHRONIZESYSGENSYSMANTFFTYPE
UILUNLOCKVIEWWAITWRITE
DECthreadsFormat of errorHintsInstructionsLexicalsLine editing
QueuesRTL RoutinesSpecifySymbol AssignSystem Services
V55 NewFeatures
DECthreads
Additional information available:
cma alert disable asynchcma alert disable generalcma alert enable asynchcma alert enable general
cma alert restorecma alert testcma attr createcma attr delete
cma attr get guardsizecma attr get inherit schedcma attr get mutex kindcma attr get priority
cma attr get schedcma attr get stacksizecma attr set guardsizecma attr set inherit sched
cma attr set mutex kindcma attr set prioritycma attr set schedcma attr set stacksize
cma cond broadcastcma cond createcma cond deletecma cond signal
cma cond signal intcma cond timed waitcma cond waitcma debug
cma debug cmdcma delaycma handle assigncma handle equal
cma initcma key createcma key get contextcma key set context
cma lib attr createcma lib attr deletecma lib attr get queuesizecma lib attr set queuesize
cma lib queue createcma lib queue deletecma lib queue dequeuecma lib queue enqueue
cma lib queue requeuecma lib queue try dequeuecma lib queue try enqueuecma lib queue try requeue
cma lib queue try enqueue intcma lock globalcma mutex create
cma mutex deletecma mutex lockcma mutex try lockcma mutex unlock
cma oncecma stack check limit npcma thread alertcma thread create
cma thread detachcma thread exit errorcma thread exit normalcma thread get priority
cma thread get schedcma thread get selfcma thread joincma thread set priority
cma thread set schedcma time get expirationcma unlock globalcma yield
pthread attr createpthread attr deletepthread attr getinheritsched
pthread attr getpriopthread attr getschedpthread attr getstacksizepthread attr setinheritsched
pthread attr setpriopthread attr setschedpthread attr setstacksizepthread cancel
pthread cleanup poppthread cleanup pushpthread condattr createpthread condattr delete
pthread cond broadcastpthread cond destroypthread cond initpthread cond signal
pthread cond timedwaitpthread cond waitpthread createpthread delay np
pthread detachpthread exitpthread get expiration nppthread getprio
pthread getschedulerpthread getspecificpthread joinpthread keycreate
pthread lock global nppthread mutexattr createpthread mutexattr deletepthread mutexattr getkind np
pthread mutexattr setkind nppthread mutex destroypthread mutex init
pthread mutex lockpthread mutex trylockpthread mutex unlockpthread once
pthread selfpthread setasynccancelpthread setcancelpthread setprio
pthread setschedulerpthread setspecificpthread testcancelpthread unlock global np
pthread yield
cma alert disable asynch
Disables asynchronous alert delivery to the current thread.
Format
cma_alert_disable_asynch (prior)
Argument Data Type Access
prior opaque cma_t_alert_ write
state
Additional information available:
Arguments
prior Receives the state of asynchronous alert delivery (enabled or disabled) that exists before the call to this routine.
cma alert disable general
Disables general delivery of alerts to the current thread.
Format
cma_alert_disable_general (prior)
Argument Data Type Access
prior opaque cma_t_alert_ write
state
Additional information available:
Arguments
prior Receives the prior state of general alert delivery (enabled or disabled).
cma alert enable asynch
Enables asynchronous alert delivery to the current thread.
Format
cma_alert_enable_asynch
Additional information available:
Arguments
None.
cma alert enable general
Enables general delivery of alerts to the current thread.
Format
cma_alert_enable_general (prior)
Argument Data Type Access
prior opaque cma_t_alert_ write
state
Additional information available:
Arguments
prior Receives the prior state of general alert delivery (enabled or disabled).
cma alert restore
Restores the state of general or asynchronous alert delivery.
Format
cma_alert_restore (prior)
Argument Data Type Access
prior opaque cma_t_alert_ read
state
Additional information available:
Arguments
prior The prior state of alert delivery (enabled or disabled).
cma alert test
Requests delivery of a pending alert to the current thread.
Format
cma_alert_test
Additional information available:
Arguments
None.
cma attr create
Creates an attributes object that can be used to specify the
attributes of other objects when they are created.
Format
cma_attr_create (new_attr, attr)
Argument Data Type Access
new_attr opaque cma_t_attr write
attr opaque cma_t_attr read
Additional information available:
Arguments
new_attr Variable that receives the new attributes object. attr Handle of the attributes object created. If you specify cma_c_null for the attr argument, default attributes are used.
cma attr delete
Deletes an attributes object.
Format
cma_attr_delete (attr)
Argument Data Type Access
attr opaque cma_t_attr modify
Additional information available:
Arguments
attr Handle of the attributes object deleted.
cma attr get guardsize
Obtains the guardsize attribute of thread creation.
Format
cma_attr_get_guardsize (attr, guardsize)
Argument Data Type Access
attr opaque cma_t_attr read
guardsize opaque cma_t_natural write
Additional information available:
Arguments
attr Handle of the attributes object whose guardsize attribute is obtained. guardsize Value of the guardsize attribute. The guardsize argument specifies the mimimum size (in bytes) of the guard area for the stack of a thread.
cma attr get inherit sched
Obtains the inherit scheduling attribute of thread creation.
Format
cma_attr_get_inherit_sched (attr, setting)
Argument Data Type Access
attr opaque cma_t_attr read
setting opaque cma_t_sched_ write
inherit
Additional information available:
Arguments
attr Handle of the attributes object whose inherit scheduling attribute is obtained. setting Receives the value for the inherit scheduling attribute. Refer to the description of cma_attr_set_inherit_sched for valid values.
cma attr get mutex kind
Obtains the mutex type attribute that is used when a mutex is
created.
Format
cma_attr_get_mutex_kind (attr, nest)
Argument Data Type Access
attr opaque cma_t_attr read
nest opaque cma_t_mutex_ write
kind
Additional information available:
Arguments
attr Mutex attributes object modified. nest Value of the mutex type attribute. The kind argument specifies the type of mutex that is created. Valid values are cma_c_mutex_fast (default), cma_c_mutex_recursive, and cma_c_mutex_nonrecursive.
cma attr get priority
Obtains the initial execution priority attribute of thread
creation.
Format
cma_attr_get_priority (attr, priority)
Argument Data Type Access
attr opaque cma_t_attr read
priority opaque cma_t_priority write
Additional information available:
Arguments
attr Handle of the attributes object whose priority attribute is obtained. priority Receives the value of the priority attribute. Refer to the description of cma_attr_set_priority for valid values.
cma attr get sched
Obtains the scheduling policy attribute of thread creation.
Format
cma_attr_get_sched (attr, policy)
Argument Data Type Access
attr opaque cma_t_attr read
policy opaque cma_t_sched_ write
policy
Additional information available:
Arguments
attr Handle of the attributes object whose scheduling policy attribute is obtained. policy Receives the value of the scheduling policy attribute. Refer to the description of cma_attr_set_sched for valid values.
cma attr get stacksize
Obtains the stacksize attribute of thread creation.
Format
cma_attr_get_stacksize (attr, stacksize)
Argument Data Type Access
attr opaque cma_t_attr read
stacksize opaque cma_t_natural write
Additional information available:
Arguments
attr Handle of the attributes object whose stacksize attribute is obtained. stacksize Value of the stacksize attribute. The stacksize argument specifies the mimimum size (in bytes) of the stack needed for a thread.
cma attr set guardsize
Changes the guardsize attribute of thread creation.
Format
cma_attr_set_guardsize (attr, guardsize)
Argument Data Type Access
attr opaque cma_t_attr read
guardsize opaque cma_t_natural read
Additional information available:
Arguments
attr Handle of the attributes object modified. guardsize New value for the guardsize attribute. The guardsize argument specifies the mimimum size (in bytes) of the guard area for the stack of a thread.
cma attr set inherit sched
Changes the inherit scheduling attribute of thread creation.
Format
cma_attr_set_inherit_sched (attr, setting)
Argument Data Type Access
attr opaque cma_t_attr read
setting opaque cma_t_sched_ read
inherit
Additional information available:
Arguments
attr
Handle of the attributes object modified.
setting
New value for the inherit priority attribute. Valid values are as
follows:
cma_c_sched_inherit This is the default value. The created
thread inherits the current priority and
scheduling policy of the thread calling cma_
thread_create.
cma_c_sched_use_ The created thread starts execution with the
default priority and scheduling policy stored in the
attributes object.
cma attr set mutex kind
Specifies the mutex type attribute that is used when a mutex is
created.
Format
cma_attr_set_mutex_kind (attr, nest)
Argument Data Type Access
attr opaque cma_t_attr read
nest opaque cma_t_mutex_ read
kind
Additional information available:
Arguments
attr Mutex attributes object modified. nest New value for the mutex type attribute. The kind argument specifies the type of mutex that is created. Valid values are cma_c_mutex_fast (default), cma_c_mutex_recursive, and cma_c_ mutex_nonrecursive.
cma attr set priority
Changes the initial execution priority attribute of thread
creation.
Format
cma_attr_set_priority (attr, priority)
Argument Data Type Access
attr opaque cma_t_attr read
priority opaque cma_t_priority read
Additional information available:
Arguments
attr
Handle of the attributes object modified.
priority
New value for the priority attribute. The priority attribute is
dependent upon scheduling policy. Valid values are as follows:
Low Mid High
cma_c_prio_fifo_ cma_prio_fifo_mid cma_prio_fifo_max
min
cma_c_prio_rr_min cma_prio_rr_mid cma_prio_rr_max
cma_c_prio_ cma_prio_through_ cma_prio_through_max
through_min mid
cma_c_prio_back_ cma_prio_back_mid cma_prio_back_max
min
The default priority is cma_prio_default_mid. (This symbol maps to
cma_prio_through_mid.) To specify a minimum, midrange, or maximum
priority, use the appropriate symbol-for example, cma_c_prio_
fifo_min or cma_c_prio_fifo_max. To specify a value between the
minimum and midrange or midrange and maximum, use an appropriate
arithmetic expression. For example, to specify a priority mid-way
between the midrange and maximum for the Round Robin scheduling
policy, specify the following concept using your programming
language's syntax:
cma_c_prio_rr_new = (cma_c_prio_rr_mid + cma_c_prio_rr_max) / 2
cma attr set sched
Changes the scheduling policy attribute of thread creation.
Format
cma_attr_set_sched (attr, policy, priority)
Argument Data Type Access
attr opaque cma_t_attr read
policy opaque cma_t_sched_ read
policy
priority opaque cma_t_priority read
Additional information available:
Arguments
attr
Handle of the attributes object modified.
policy
New value for the scheduling policy attribute. Valid values are as
follows:
cma_c_sched_fifo (First In, First Out) The highest priority
thread executes until it blocks, or until
a higher priority thread becomes ready to
execute. Higher priority threads immediately
preempt lower priority threads.
cma_c_sched_rr (Round Robin) Like cma_c_sched_fifo, the
highest priority thread executes until
it blocks, or until a higher priority
thread becomes ready to execute. However,
threads of equal priority are timesliced.
(Timeslicing is a process in which threads
are allowed to execute only for a certain
amount of time before giving up the
processor.) This ensures fairness among
threads of equal priority.
cma_c_sched_ (Default) All threads are timesliced. This
throughput ensures that all threads, regardless of
priority, receive some scheduling so no
thread is completely denied execution time.
However, cma_c_sched_throughput threads can
be denied execution time by cma_c_sched_fifo
or cma_c_sched_rr threads. All cma_c_sched_
throughput threads have a lower priority
than cma_c_sched_fifo and cma_c_sched_rr
threads.
cma_c_sched_ All threads are timesliced. cma_c_sched_
background background threads can be preempted by cma_
c_sched_fifo and cma_c_sched_rr threads.
However, they are guaranteed to eventually
make progress against compute-bound cma_c_
sched_throughput threads.
priority
New value for the priority attribute. The priority attribute is
dependent upon scheduling policy. Valid values are as follows:
Low Mid High
cma_c_prio_fifo_ cma_prio_fifo_mid cma_prio_fifo_max
min
cma_c_prio_rr_min cma_prio_rr_mid cma_prio_rr_max
cma_c_prio_ cma_prio_through_ cma_prio_through_max
through_min mid
cma_c_prio_back_ cma_prio_back_mid cma_prio_back_max
min
The default priority is cma_prio_default_mid. (This symbol maps to
cma_prio_through_mid.) To specify a minimum, midrange, or maximum
priority, use the appropriate symbol-for example, cma_c_prio_
fifo_min or cma_c_prio_fifo_max. To specify a value between the
minimum and midrange or midrange and maximum, use an appropriate
arithmetic expression. For example, to specify a priority mid-way
between the midrange and maximum for the Round Robin scheduling
policy, specify the following concept using your programming
language's syntax:
cma_c_prio_rr_new = (cma_c_prio_rr_mid + cma_c_prio_rr_max) / 2
cma attr set stacksize
Changes the stacksize attribute of thread creation.
Format
cma_attr_set_stacksize (attr, stacksize)
Argument Data Type Access
attr opaque cma_t_attr read
stacksize opaque cma_t_natural read
Additional information available:
Arguments
attr Handle of the attributes object modified. stacksize New value for the stacksize attribute. The stacksize argument specifies the mimimum size (in bytes) of the stack needed for a thread.
cma cond broadcast
Wakes all threads that are waiting on a condition variable.
Format
cma_cond_broadcast (condition)
Argument Data Type Access
condition opaque cma_t_cond read
Additional information available:
Arguments
condition Handle of the condition variable broadcast.
cma cond create
Creates a condition variable.
Format
cma_cond_create (new_condition, attr)
Argument Data Type Access
new_condition opaque cma_t_cond write
attr opaque cma_t_attr read
Additional information available:
Arguments
new_condition Variable that receives the handle for the new condition variable. attr Handle of the attributes object that defines the characteristics of the condition variable being created.
cma cond delete
Deletes a condition variable.
Format
cma_cond_delete (condition)
Argument Data Type Access
condition opaque cma_t_cond modify
Additional information available:
Arguments
condition Handle of the condition variable deleted.
cma cond signal
Wakes one thread that is waiting on a condition variable.
Format
cma_cond_signal (condition)
Argument Data Type Access
condition opaque cma_t_cond read
Additional information available:
Arguments
condition Handle of the condition variable signaled.
cma cond signal int
Wakes one thread that is waiting on a condition variable. This
routine can be called from interrupt level.
Format
cma_cond_signal (condition)
Argument Data Type Access
condition opaque cma_t_cond read
Additional information available:
Arguments
condition Handle of the condition variable signaled.
cma cond timed wait
Causes a thread to wait for a condition variable to be signaled or
broadcast for a specified period of time.
Format
status = cma_cond_timed_wait (condition, mutex, expiration)
Argument Data Type Access
status opaque cma_t_status write
condition opaque cma_t_cond read
mutex opaque cma_t_mutex read
expiration opaque cma_t_date_time read
Additional information available:
Arguments
status Variable that receives the return status. Valid values are cma_s_ normal and cma_s_timed_out. condition Handle of the condition variable on which the thread waits. mutex Mutex associated with the condition variable specified in condition. expiration Absolute time at which the wait should expire, if the condition has not yet been signaled or broadcast. (See the cma_time_get_ expiration routine, which can be used to obtain a value for this argument.)
cma cond wait
Causes a thread to wait for a condition variable to be signaled or
broadcast.
Format
cma_cond_wait (condition, mutex)
Argument Data Type Access
condition opaque cma_t_cond read
mutex opaque cma_t_mutex read
Additional information available:
Arguments
condition Handle of the condition variable on which the thread waits. mutex Mutex associated with the condition variable specified in condition.
cma debug
Invokes the debugger.
Format
cma_debug
Additional information available:
Arguments
None.
cma debug cmd
Passes a list of cma_debug commands to DECthreads.
Format
cma_debug_cmd (command)
Argument Data Type Access
command character string read
Additional information available:
Arguments
command cma_debug command string(s). The final argument must be a null argument (NULL, cma_c_null_ptr, or 0).
cma delay
Causes a thread to wait for a specified period of time before
continuing execution.
Format
cma_delay (time_interval)
Argument Data Type Access
time_interval single floating point read
Additional information available:
Arguments
interval Number of seconds that the calling thread waits before continuing execution. Specify a value greater than or equal to 0.
cma handle assign
Assigns a handle to an object.
Format
cma_handle_assign (handle1, handle2)
Argument Data Type Access
handle1 opaque cma_t_handle read
handle2 opaque cma_t_handle write
Additional information available:
Arguments
handle1 Handle that is assigned to handle2. handle2 Handle that receives the value from handle1.
cma handle equal
Compares a handle to another handle.
Format
equal = cma_handle_equal (handle1, handle2)
Argument Data Type Access
equal Boolean cma_t_boolean write
handle1 opaque cma_t_handle read
handle2 opaque cma_t_handle read
Additional information available:
Arguments
equal Boolean value that specifies whether handle1 and handle2 designate the same object. handle1 The first handle to be compared. handle2 The second handle to be compared.
cma init
Initializes the DECthreads routines.
Format
cma_init
Additional information available:
Arguments
None.
cma key create
Generates a unique per-thread context key value.
Format
cma_key_create (key, attr, destructor)
Argument Data Type Access
key opaque cma_t_key write
attr opaque cma_t_attr read
destructor procedure cma_t_ read
destructor
Additional information available:
Arguments
key Receives the value of the new per-thread context key. attr Handle of the attributes object that defines the characteristics of the per-thread context key being created. destructor Procedure called to destroy a context value associated with this key when the thread terminates, or when the value is changed (for example, by calling cma_key_set_context.)
cma key get context
Obtains the per-thread context associated with the specified key.
Format
cma_key_get_context (key, context_value)
Argument Data Type Access
key opaque cma_t_key read
context_value opaque cma_t_address write
Additional information available:
Arguments
key Context key value that uniquely identifies the context value obtained. This key value must have been obtained from cma_key_ create. context_value Variable that receives the address of the current per-thread context value associated with the specified key.
cma key set context
Sets the per-thread context associated with the specified key for
the current thread.
Format
cma_key_set_context (key, context_value)
Argument Data Type Access
key opaque cma_t_key read
context_value opaque cma_t_address read
Additional information available:
Arguments
key Context key value that uniquely identifies the context value specified in context_value. This key value must have been obtained from cma_key_create. context_value Address containing data associated with the specified key for the current thread; this is the per-thread context.
cma lib attr create
Creates a library attributes object.
Format
cma_lib_attr_create (new_attr, attr)
Argument Data Type Access
new_attr opaque cma_lib_t_attr write
attr opaque cma_lib_t_attr read
Additional information available:
Arguments
new_attr Variable that receives a handle for the new attributes object. attr Handle of the attributes object created. If you specify cma_c_null for the attr argument, default attributes are used.
cma lib attr delete
Deletes a library attributes object.
Format
cma_lib_attr_delete (attr)
Argument Data Type Access
attr opaque cma_lib_t_attr read, write
Additional information available:
Arguments
attr Handle of the attributes object deleted.
cma lib attr get queuesize
Obtains the maximum number of elements available on an atomic
queue attribute that is used when a queue is created.
Format
cma_lib_attr_get_queuesize (attr, queuesize)
Argument Data Type Access
attr opaque cma_lib_t_attr read
nest opaque cma_t_natural write
Additional information available:
Arguments
attr Handle of the library attributes object. This value is returned by cma_lib_attr_create. nest Variable that receives the current value of the queuesize attribute.
cma lib attr set queuesize
Specifies the attribute for the maximum number of elements allowed
on an atomic queue that is used when a queue is created.
Format
cma_lib_attr_set_queuesize (attr, queuesize)
Argument Data Type Access
attr opaque cma_lib_t_attr read
nest opaque cma_t_natural read
Additional information available:
Arguments
attr Handle of the library attributes object to be modified. This value is returned by cma_lib_attr_create. nest New value for the queue size attribute. The default value is 128.
cma lib queue create
Creates an atomic queue.
Format
cma_lib_queue_create (new_queue, attr )
Argument Data Type Access
new_queue opaque cma_lib_t_queue write
attr opaque cma_lib_t_attr read
Additional information available:
Arguments
new_queue Variable that receives the handle of the atomic queue created. attr Library attributes object used when creating the queue.
cma lib queue delete
Deletes an atomic queue.
Format
cma_lib_queue_delete (queue)
Argument Data Type Access
queue opaque cma_lib_t_queue read, write
Additional information available:
Arguments
queue Handle of the queue to be deleted.
cma lib queue dequeue
Removes the first element from an atomic queue.
Format
cma_lib_queue_dequeue (queue, element)
Argument Data Type Access
queue opaque cma_lib_t_queue read
element opaque cma_t_address write
Additional information available:
Arguments
queue Handle of the queue from which the element is removed. element Variable that receives the address of the removed queue element.
cma lib queue enqueue
Inserts an element at the end of an atomic queue.
Format
cma_lib_queue_enqueue (queue, element)
Argument Data Type Access
queue opaque cma_lib_t_queue read
element opaque cma_t_address read
Additional information available:
Arguments
queue Handle of the queue to which the element is inserted. element Address of the queue element inserted.
cma lib queue requeue
Inserts an element at the front of an atomic queue.
Format
cma_lib_queue_requeue (queue, element)
Argument Data Type Access
queue opaque cma_lib_t_queue read
element opaque cma_t_address read
Additional information available:
Arguments
queue Handle of the queue to which the element is inserted. element Address of the queue element inserted.
cma lib queue try dequeue
Removes the first element from an atomic queue. If the queue
is empty, the calling thread does not wait for an element to be
enqueued.
Format
status = cma_lib_queue_try_dequeue (queue, element)
Argument Data Type Access
status Boolean cma_t_boolean write
queue opaque cma_lib_t_queue read
element opaque cma_t_address write
Additional information available:
Arguments
status Boolean value that specifies whether the element was dequeued. Valid values are cma_t_true and cma_t_false. queue Handle of the queue from which the element is removed. element Variable that receives the address of the removed queue element.
cma lib queue try enqueue
Inserts an element at the end of an atomic queue. If the queue
is full, the calling thread does not wait for an element to be
removed.
Format
status = cma_lib_queue_try_enqueue (queue, element)
Argument Data Type Access
status Boolean cma_t_boolean write
queue opaque cma_lib_t_queue read
element opaque cma_t_address read
Additional information available:
Arguments
status Boolean value that specifies whether the element was enqueued. Valid values are cma_t_true and cma_t_false. queue Handle of the queue to which the element is inserted. element Address of the queue element inserted.
cma lib queue try requeue
Inserts an element at the front of an atomic queue. If the queue
is full, the calling thread does not wait for an element to be
removed.
Format
status = cma_lib_queue_try_requeue (queue, element)
Argument Data Type Access
status Boolean cma_t_boolean write
queue opaque cma_lib_t_queue read
element opaque cma_t_address read
Additional information available:
Arguments
status Boolean value that specifies whether the element was requeued. Valid values are cma_t_true and cma_t_false. queue Handle of the queue to which the element is inserted. element Address of the queue element inserted.
cma lib queue try enqueue int
Inserts an element at the end of an atomic queue from interrupt
level. If the queue is full, the calling thread does not wait for
an element to be removed.
Format
status = cma_lib_queue_try_enqueue_int (queue, element)
Argument Data Type Access
status Boolean cma_t_boolean write
queue opaque cma_lib_t_queue read
element opaque cma_t_address read
Additional information available:
Arguments
status Boolean value that specifies whether the element was enqueued. Valid values are cma_t_true and cma_t_false. queue Handle of the queue to which the element is inserted. element Address of the queue element inserted.
cma lock global
Locks the global mutex.
Format
cma_lock_global
Additional information available:
Arguments
None.
cma mutex create
Creates a mutex.
Format
cma_mutex_create (new_mutex, attr)
Argument Data Type Access
new_mutex opaque cma_t_mutex write
attr opaque cma_t_attr read
Additional information available:
Arguments
new_mutex Receives a handle for the mutex. attr Handle of the attributes object that defines the characteristics of the mutex created. If you specify cma_c_null, default attributes are used.
cma mutex delete
Deletes a mutex.
Format
cma_mutex_delete (mutex)
Argument Data Type Access
mutex opaque cma_t_mutex modify
Additional information available:
Arguments
mutex Handle of the mutex deleted. After the call to this routine, the mutex argument is set to the value cma_c_null.
cma mutex lock
Locks a mutex if the mutex is unlocked. If the mutex is locked,
causes the thread to wait for the mutex to become available.
Format
cma_mutex_lock (mutex)
Argument Data Type Access
mutex opaque cma_t_mutex read
Additional information available:
Arguments
mutex Handle of the mutex locked.
cma mutex try lock
Locks a mutex. If the mutex is already locked, the calling thread
does not wait for the mutex to become available.
Format
status = cma_mutex_try_lock (mutex)
Argument Data Type Access
status Boolean cma_t_boolean write
mutex opaque cma_t_mutex read
Additional information available:
Arguments
status Boolean value that specifies whether the element was successfully locked. Valid values are cma_t_true and cma_t_false. mutex Handle of the mutex to be locked.
cma mutex unlock
Unlocks a mutex.
Format
cma_mutex_unlock (mutex)
Argument Data Type Access
mutex opaque cma_t_mutex read
Additional information available:
Arguments
mutex Handle of the mutex unlocked.
cma once
Calls an initialization routine that can be executed by only one
thread, a single time.
Format
cma_once (init_block, init_routine, arg)
Argument Data Type Access
init_block opaque cma_t_once read
init_routine opaque cma_t_init_ read
routine
arg opaque cma_t_address read
Additional information available:
Arguments
init_block Address of a record that defines the one-time initialization code. Each one-time initialization routine must have its own unique cma_ t_once. init_routine Address of a procedure that performs the initialization. This routine is called only once, regardless of the number of times it and its associated init_block are passed to cma_once. arg Argument passed to the init_routine.
cma stack check limit np
Determines whether sufficient space exists on the current thread's
stack to allocate the requested number of bytes of local storage.
Format
status = cma_stack_check_limit_np (size)
Argument Data Type Access
status Boolean cma_t_boolean write
size opaque cma_t_integer read
Additional information available:
Arguments
status Boolean value that specifies whether the requested size does not extend beyond the current thread's stack. Valid values are cma_t_ true and cma_t_false. size Number of bytes requested. DECthreads determines whether a stack allocation of the specified size extends beyond the end of the thread's stack.
cma thread alert
Cancels thread execution.
Format
cma_thread_alert (thread)
Argument Data Type Access
thread opaque cma_t_thread read
Additional information available:
Arguments
thread Handle of the thread that receives an alert.
cma thread create
Creates a thread object and thread.
Format
cma_thread_create (new_thread, attr, start_routine, arg)
Argument Data Type Access
new_thread opaque cma_t_thread write
attr opaque cma_t_attr read
start_routine cma_t_start_routine read
arg pointer read
Additional information available:
Arguments
new_thread Variable that receives a handle for the thread object. attr Handle of the attributes object that defines the characteristics of the thread being created. If you specify cma_c_null, default attributes are used. start_routine Function executed as the new thread's start routine. This argument is the address of a routine that takes one argument of type cma_t_ address, and returns a value of type cma_t_address. arg Address value that is copied and passed to the thread's start routine.
cma thread detach
Marks a thread object for deletion.
Format
cma_thread_detach (thread)
Argument Data Type Access
thread opaque cma_t_thread modify
Additional information available:
Arguments
thread Handle of the thread object marked for deletion.
cma thread exit error
Terminates the current thread when an error occurs.
Format
cma_thread_exit_error
Additional information available:
Arguments
None.
cma thread exit normal
Terminates the current thread when successful completion occurs
prematurely.
Format
cma_thread_exit_normal (result)
Argument Data Type Access
result opaque cma_t_address read
Additional information available:
Arguments
result Address value that is copied and returned to the caller of cma_ thread_join.
cma thread get priority
Obtains the current priority of a thread.
Format
cma_thread_get_priority (thread, priority)
Argument Data Type Access
thread opaque cma_t_thread read
priority opaque cma_t_priority write
Additional information available:
Arguments
thread Handle of the thread whose priority is obtained. priority Variable that rthe current priority value of the thread specified in thread. Refer to the description of cma_thread_set_priority for valid values.
cma thread get sched
Obtains the current scheduling policy of a thread.
Format
cma_thread_get_sched (thread, policy)
Argument Data Type Access
thread opaque cma_t_thread read
policy opaque cma_t_sched_ write
policy
Additional information available:
Arguments
thread Handle of the thread whose scheduling policy is obtained. policy Variable that receives the current scheduling policy value of the thread specified in thread. Refer to the description of cma_ thread_set_sched for valid values.
cma thread get self
Obtains the handle of the current thread.
Format
cma_thread_get_self (thread)
Argument Data Type Access
thread opaque cma_t_thread write
Additional information available:
Arguments
thread Variable that receives the handle of the current thread.
cma thread join
Causes the calling thread to wait for the termination of a
specified thread.
Format
cma_thread_join (thread, exit_status, result)
Argument Data Type Access
thread opaque cma_t_thread read
exit_status opaque cma_t_exit_ write
status
result pointer write
Additional information available:
Arguments
thread
Handle of the thread whose termination is awaited by the caller of
this routine.
exit_status
Variable that receives a value indicating whether the thread
specified by thread successfully terminated. Valid values are
as follows:
cma_c_term_normal Normal termination
cma_c_term_error Error termination (because of an unhandled
exception)
cma_c_term_alert Alert termination
result
Address value that is optionally returned by the start_routine of
the thread specified by the thread argument in its call to cma_
thread_create.
cma thread set priority
Changes the current priority of a thread.
Format
cma_thread_set_priority (thread, priority)
Argument Data Type Access
thread opaque cma_t_thread read
priority opaque cma_t_priority read
Additional information available:
Arguments
thread
Handle of the thread whose priority is changed.
priority
New value of the priority attribute. The priority attribute is
dependent upon scheduling policy. Valid values are as follows:
Low Mid High
cma_c_prio_fifo_ cma_prio_fifo_mid cma_prio_fifo_max
min
cma_c_prio_rr_min cma_prio_rr_mid cma_prio_rr_max
cma_c_prio_ cma_prio_through_ cma_prio_through_max
through_min mid
cma_c_prio_back_ cma_prio_back_mid cma_prio_back_max
min
The default priority is cma_prio_default_mid. (This symbol maps to
cma_prio_through_mid.) To specify a minimum, midrange, or maximum
priority, use the appropriate symbol-for example, cma_c_prio_
fifo_min or cma_c_prio_fifo_max. To specify a value between the
minimum and midrange or midrange and maximum, use an appropriate
arithmetic expression. For example, to specify a priority mid-way
between the midrange and maximum for the Round Robin scheduling
policy, specify the following concept using your programming
language's syntax:
cma_c_prio_rr_new = (cma_c_prio_rr_mid + cma_c_prio_rr_max) / 2
cma thread set sched
Changes the current scheduling policy and priority of a thread.
Format
cma_thread_set_sched (thread, policy, priority)
Argument Data Type Access
thread opaque cma_t_thread read
policy opaque cma_t_sched_ read
policy
priority opaque cma_t_priority read
Additional information available:
Arguments
thread
Handle of the thread whose scheduling policy is changed.
policy
New scheduling policy value of the thread specified in thread.
Valid values are as follows:
cma_c_sched_fifo (First In, First Out) The highest priority
thread executes until it blocks, or until
a higher priority thread becomes ready to
execute. Higher priority threads immediately
preempt lower priority threads.
cma_c_sched_rr (Round Robin) Like cma_c_sched_fifo, the
highest priority thread executes until
it blocks, or until a higher priority
thread becomes ready to execute. However,
threads of equal priority are timesliced.
(Timeslicing is a process in which threads
are allowed to execute only for a certain
amount of time before giving up the
processor.) This ensures fairness among
threads of equal priority.
cma_c_sched_ (Default) All threads are timesliced. This
throughput ensures that all threads, regardless of
priority, receive some scheduling so no
thread is completely denied execution time.
However, cma_c_sched_throughput threads can
be denied execution time by cma_c_sched_fifo
or cma_c_sched_rr threads. All cma_c_sched_
throughput threads have a lower priority
than cma_c_sched_fifo and cma_c_sched_rr
threads.
cma_c_sched_ All threads are timesliced. cma_c_sched_
background background threads can be preempted by cma_
c_sched_fifo and cma_c_sched_rr threads.
However, they are guaranteed to eventually
make progress against compute-bound cma_c_
sched_throughput threads.
priority
New priority value of the thread specified in thread. The priority
value is dependent upon scheduling policy. Valid values are as
follows:
Low Mid High
cma_c_prio_fifo_ cma_prio_fifo_mid cma_prio_fifo_max
min
cma_c_prio_rr_min cma_prio_rr_mid cma_prio_rr_max
cma_c_prio_ cma_prio_through_ cma_prio_through_max
through_min mid
cma_c_prio_back_ cma_prio_back_mid cma_prio_back_max
min
The default priority is cma_prio_default_mid. (This symbol maps to
cma_prio_through_mid.) To specify a minimum, midrange, or maximum
priority, use the appropriate symbol-for example, cma_c_prio_
fifo_min or cma_c_prio_fifo_max. To specify a value between the
minimum and midrange or midrange and maximum, use an appropriate
arithmetic expression. For example, to specify a priority mid-way
between the midrange and maximum for the Round Robin scheduling
policy, specify the following concept using your programming
language's syntax:
cma_c_prio_rr_new = (cma_c_prio_rr_mid + cma_c_prio_rr_max) / 2
cma time get expiration
Obtains a cma_t_date_time value representing a desired expiration
time.
Format
cma_time_get_expiration (expiration, interval)
Argument Data Type Access
expiration opaque cma_t_date_time write
interval opaque cma_t_interval read
Additional information available:
Arguments
expiration Variable that receives the cma_t_date_time value representing the expiration time. interval Number of seconds to add to the current system time. The result is the time that the timed wait should expire.
cma unlock global
Unlocks a global mutex.
Format
cma_unlock_global
Additional information available:
Arguments
None.
cma yield
Notifies the scheduler that the current thread is willing to
release its processor to other threads of the same priority.
Format
cma_yield
Additional information available:
Arguments
None.
pthread attr create
Format
pthread_attr_create(
attr );
Additional information available:
Arguments
attr Thread attributes object created.
pthread attr delete
Format
pthread_attr_delete(
attr );
Additional information available:
Arguments
attr Thread attributes object deleted.
pthread attr getinheritsched
Format
pthread_attr_getinheritsched(
attr );
Additional information available:
Arguments
attr Thread attributes object whose inherit scheduling attribute is obtained.
pthread attr getprio
Format
pthread_attr_getprio(
attr );
Additional information available:
Arguments
attr Thread attributes object whose priority attribute is obtained.
pthread attr getsched
Format
pthread_attr_getsched(
attr );
Additional information available:
Arguments
attr Thread attributes object whose scheduling policy attribute is obtained.
pthread attr getstacksize
Format
pthread_attr_getstacksize(
attr );
Additional information available:
Arguments
attr Thread attributes object whose stacksize attribute is obtained.
pthread attr setinheritsched
Format
pthread_attr_setinheritsched(
attr,
inherit );
Additional information available:
Arguments
attr
Thread attributes object to be modified.
inherit
New value for the inherit scheduling attribute. Valid values are
as follows:
INHERIT_SCHED This is the default value. The created
thread inherits the current priority and
scheduling policy of the thread calling
pthread_create.
DEFAULT_SCHED The created thread starts execution with the
priority and scheduling policy stored in the
thread attributes object.
pthread attr setprio
Format
pthread_attr_setprio(
attr,
priority );
Additional information available:
Arguments
attr
Thread attributes object modified.
priority
New value for the priority attribute. The priority attribute is
dependent upon scheduling policy. Valid values fall within one of
the following three ranges.
Low High
PRI_OTHER_MIN PRI_OTHER_MAX
PRI_FIFO_MIN PRI_FIFO_MAX
PRI_RR_MIN PRI_RR_MAX
The default priority is the midpoint between PRI_OTHER_MIN and
PRI_OTHER_MAX. To specify a minimum or maximum priority, use
the appropriate symbol-for example, PRI_FIFO_MIN or PRI_FIFO_
MAX. To specify a value between the minimum and maximum, use
an appropriate arithmetic expression. For example, to specify
a priority mid-way between the minimum and maximum for the Round
Robin scheduling policy, specify the following concept using your
programming language's syntax:
pri_rr_mid = (PRI_RR_MIN + PRI_RR_MAX) / 2
If your expression results in a value outside the range of minimum
to maximum, an error results when you attempt to use it.
pthread attr setsched
Format
pthread_attr_setsched(
attr,
scheduler );
Additional information available:
Arguments
attr
Threads attributes object modified.
scheduler
New value for the scheduling policy attribute. Valid values are as
follows:
SCHED_FIFO (First In, First Out) The highest priority
thread runs until it blocks. If there is
more than one thread with the same priority,
and that priority is the highest among other
threads, the first thread to begin running
continues until it blocks.
SCHED_RR (Round Robin) The highest priority thread
runs until it blocks; however, threads of
equal priority, if that priority is the
highest among other threads, are timesliced.
Timeslicing is a process in which threads
alternate using available processors.
SCHED_OTHER (Default) All threads are timesliced. SCHED_
OTHER ensures that all threads, regardless
of priority, receive some scheduling so no
thread is completely denied execution time.
(However, SCHED_OTHER threads can be denied
execution time by SCHED_FIFO or SCHED_RR
threads.)
pthread attr setstacksize
Format
pthread_attr_setstacksize(
attr,
stacksize );
Additional information available:
Arguments
attr Threads attributes object modified. stacksize New value for the stacksize attribute. The stacksize argument specifies the minimum size (in bytes) of stack needed for a thread.
pthread cancel
Format
pthread_cancel(
thread );
Additional information available:
Arguments
thread Thread that receives a cancel request.
pthread cleanup pop
Format
pthread_cleanup_pop(
execute );
Additional information available:
Arguments
execute Integer that specifies whether the cleanup routine in pthread_ cleanup_push is executed when the thread terminates normally (for example, when pthread_exit is called). If the value of execute is 0, the routine is executed only if the thread terminates abnormally (for example, if the thread is canceled). If the value is 1 or more, the routine is executed regardless of whether the thread terminates normally or abnormally.
pthread cleanup push
Format
pthread_cleanup_push(
routine,
arg );
Additional information available:
Arguments
routine Routine executed as the cleanup handler. arg Argument executed with the cleanup routine.
pthread condattr create
Format
pthread_condattr_create(
attr );
Additional information available:
Arguments
attr Condition variable attributes object that is created.
pthread condattr delete
Format
pthread_condattr_delete(
attr );
Additional information available:
Arguments
attr Condition variable attributes object deleted.
pthread cond broadcast
Format
pthread_cond_broadcast(
cond );
Additional information available:
Arguments
cond Condition variable broadcast.
pthread cond destroy
Format
pthread_cond_destroy(
cond );
Additional information available:
Arguments
cond Condition variable deleted.
pthread cond init
Format
pthread_cond_init(
cond,
attr );
Additional information available:
Arguments
cond Condition variable that is created. attr Condition variable attributes object that defines the characteristics of the condition variable created. If you specify PTHREAD_CONDATTR_DEFAULT, default attributes are used.
pthread cond signal
Format
pthread_cond_signal(
cond );
Additional information available:
Arguments
cond Condition variable signaled.
pthread cond timedwait
Format
pthread_cond_timedwait(
cond,
mutex,
abstime );
Additional information available:
Arguments
cond Condition variable waited on. mutex Mutex associated with the condition variable specified in cond. abstime Absolute time at which the wait expires, if the condition has not been signaled or broadcast. (See the pthread_get_expiration_np routine, which is used to obtain a value for this argument.)
pthread cond wait
Format
pthread_cond_wait(
cond,
mutex );
Additional information available:
Arguments
cond Condition variable waited on. mutex Mutex associated with the condition variable specified in cond.
pthread create
Format
pthread_create(
thread,
attr,
start_routine,
arg );
Additional information available:
Arguments
thread Thread object created. attr Thread attributes object that defines the characteristics of the thread being created. If you specify PTHREAD_ATTR_DEFAULT, default attributes are used. start_routine Function executed as the new thread's start routine. arg Address value copied and passed to the thread's start routine.
pthread delay np
Format
pthread_delay_np(
interval );
Additional information available:
Arguments
interval Number of seconds and nanoseconds that the calling thread waits before continuing execution. The value specified must be greater than or equal to 0.
pthread detach
Format
pthread_detach(
thread );
Additional information available:
Arguments
thread Thread object marked for deletion.
pthread exit
Format
pthread_exit(
status );
Additional information available:
Arguments
status Address value copied and returned to the caller of pthread_join.
pthread get expiration np
Format
pthread_get_expiration_np(
delta,
abstime );
Additional information available:
Arguments
delta Number of seconds and nanoseconds to add to the current system time. The result is the time that a timed wait expires. abstime Value representing the expiration time.
pthread getprio
Format
pthread_getprio(
thread );
Additional information available:
Arguments
thread Thread whose priority is obtained.
pthread getscheduler
Format
pthread_getscheduler(
thread );
Additional information available:
Arguments
thread Thread whose scheduling policy is obtained.
pthread getspecific
Format
pthread_getspecific(
key,
value );
Additional information available:
Arguments
key Context key value that identifies the context value obtained. This key value must be obtained from pthread_keycreate, or it must be a key value predefined by the implementation (if predefined key values are provided). value Address of the current per-thread context value associated with the specified key.
pthread join
Format
pthread_join(
thread,
status );
Additional information available:
Arguments
thread Thread whose termination is awaited by the caller of this routine. status Status value of the terminating thread (in other words, when that thread calls pthread_exit.)
pthread keycreate
Format
pthread_keycreate(
key,
destructor );
Additional information available:
Arguments
key Value of the new per-thread context key. destructor Procedure called to destroy a context value associated with the created key when the thread terminates.
pthread lock global np
Format
pthread_lock_global_np();
Additional information available:
Arguments
None.
pthread mutexattr create
Format
pthread_mutexattr_create(
attr );
Additional information available:
Arguments
attr Mutex attributes object created.
pthread mutexattr delete
Format
pthread_mutexattr_delete(
attr );
Additional information available:
Arguments
attr Attributes object deleted.
pthread mutexattr getkind np
Format
pthread_mutexattr_getkind_np(
attr );
Additional information available:
Arguments
attr Mutex attributes object modified.
pthread mutexattr setkind np
Format
pthread_mutexattr_setkind_np(
attr,
kind );
Additional information available:
Arguments
attr Mutex attributes object modified. kind New value for the mutex type attribute. The kind argument specifies the type of mutex that is created. Valid values are MUTEX_FAST (default), MUTEX_RECURSIVE, and MUTEX_NONRECURSIVE.
pthread mutex destroy
Format
pthread_mutex_destroy(
mutex );
Additional information available:
Arguments
mutex Mutex deleted.
pthread mutex init
Format
pthread_mutex_init(
mutex,
attr );
Additional information available:
Arguments
mutex Mutex created. attr Mutex attributes object that defines the characteristics of the created mutex. If you specify PTHREAD_MUTEXATTR_DEFAULT, default attributes are used.
pthread mutex lock
Format
pthread_mutex_lock(
mutex );
Additional information available:
Arguments
mutex Mutex locked.
pthread mutex trylock
Format
pthread_mutex_trylock(
mutex );
Additional information available:
Arguments
mutex Mutex locked.
pthread mutex unlock
Format
pthread_mutex_unlock(
mutex );
Additional information available:
Arguments
mutex Mutex unlocked.
pthread once
Format
pthread_once(
once_block,
init_routine );
Additional information available:
Arguments
once_block Address of a record that defines the one-time initialization code. Each one-time initialization routine must have its own unique pthread_once_t. init_routine Address of a procedure that performs the initialization. This routine is called only once, regardless of the number of times it and its associated once_block are passed to pthread_once.
pthread self
Format
pthread_self();
Additional information available:
Arguments
None.
pthread setasynccancel
Format
pthread_setasynccancel(
state );
Additional information available:
Arguments
state State of asynchronous cancelability set for the calling thread. On return, receives the prior state of asynchronous cancelability. Valid values are as follows: CANCEL_ON Asynchronous cancelability is enabled. CANCEL_OFF Asynchronous cancelability is disabled.
pthread setcancel
Format
pthread_setcancel(
state );
Additional information available:
Arguments
state State of general cancelability set for the calling thread. On return, receives the prior state of general cancelability. Valid values are as follows: CANCEL_ON General cancelability is enabled. CANCEL_OFF General cancelability is disabled.
pthread setprio
Format
pthread_setprio(
thread,
priority );
Additional information available:
Arguments
thread
Thread whose priority is changed.
priority
New priority value of the thread specified in thread. The priority
value is dependent upon scheduling policy. Valid values fall
within one of the following three ranges.
Low High
PRI_OTHER_MIN PRI_OTHER_MAX
PRI_FIFO_MIN PRI_FIFO_MAX
PRI_RR_MIN PRI_RR_MAX
If you create a new thread without specifying a threads attributes
object that contains a changed priority attribute, the default
priority of the newly created thread is the midpoint between PRI_
OTHER_MIN and PRI_OTHER_MAX (the midpoint between the minimum
and the maximum for the SCHED_OTHER policy). When you call
this routine to specify a minimum or maximum priority, use the
appropriate symbol-for example, PRI_FIFO_MIN or PRI_FIFO_MAX.
To specify a value between the minimum and maximum, use an
appropriate arithmetic expression. For example, to specify a
priority mid-way between the minimum and maximum for the Round
Robin scheduling policy, specify the following concept using your
programming language's syntax:
pri_rr_mid = (PRI_RR_MIN + PRI_RR_MAX) / 2
If your expression results in a value outside the range of minimum
to maximum, an error results when you use it.
pthread setscheduler
Format
pthread_setscheduler(
thread,
scheduler,
priority );
Additional information available:
Arguments
thread
Thread whose scheduling policy is to be changed.
scheduler
New scheduling policy value for the thread specified in thread.
Valid values are as follows:
SCHED_FIFO (First In, First Out) The highest priority
thread runs until it blocks. If there is
more than one thread with the same priority,
and that priority is the highest among other
threads, the first thread to begin running
continues until it blocks.
SCHED_RR (Round Robin) The highest priority thread
runs until it blocks; however, threads of
equal priority, if that priority is the
highest among other threads, are timesliced.
Timeslicing is a process in which threads
alternate using available processors.
SCHED_OTHER (Default) All threads are timesliced. SCHED_
SCHED_FG_NP OTHER ensures that all threads, regardless
of priority, receive some scheduling,
and thus no thread is completely denied
execution time. (However, SCHED_OTHER
threads can be denied execution time by
SCHED_FIFO or SCHED_RR threads.)
SCHED_BG_NP (Background) Like SCHED_OTHER, ensures that
all threads, regardless of priority, receive
some scheduling. However, SCHED_BG_NP may
be denied execution by any of the other
scheduling policies.
priority
New priority value of the thread specified in thread. The priority
attribute is dependent upon scheduling policy. Valid values fall
within one of the following three ranges.
Low High
PRI_OTHER_MIN PRI_OTHER_MAX
PRI_FIFO_MIN PRI_FIFO_MAX
PRI_RR_MIN PRI_RR_MAX
PRI_FG_MIN_NP PRI_FG_MAX_NP
PRI_BG_MIN_NP PRI_BG_MAX_NP
If you create a new thread without specifying a threads attributes
object that contains a changed priority attribute, the default
priority of the newly created thread is the midpoint between PRI_
OTHER_MIN and PRI_OTHER_MAX (the midpoint between the minimum
and the maximum for the SCHED_OTHER policy). When you call
this routine to specify a minimum or maximum priority, use the
appropriate symbol-for example, PRI_FIFO_MIN or PRI_FIFO_MAX.
To specify a value between the minimum and maximum, use an
appropriate arithmetic expression. For example, to specify a
priority mid-way between the minimum and maximum for the Round
Robin scheduling policy, specify the following concept using your
programming language's syntax:
pri_rr_mid = (PRI_RR_MIN + PRI_RR_MAX) / 2
If your expression results in a value outside the range of minimum
to maximum, an error results when you use it.
pthread setspecific
Format
pthread_setspecific(
key,
value );
Additional information available:
Arguments
key Context key value that uniquely identifies the context cell to receive value. This key value must be obtained from pthread_ keycreate, or it must be a key value predefined by the implementation (if predefined key values are provided.) value Address containing data associated with the specified key for the current thread; this is the per-thread context.
pthread testcancel
Format
pthread_testcancel();
Additional information available:
Arguments
None.
pthread unlock global np
Format
pthread_unlock_global_np();
Additional information available:
Arguments
None.
pthread yield
Format
pthread_yield();
Additional information available:
Arguments
None.
Format of error
Errors are displayed in the format:
%facility-l-ident, text
facility is the name of the facility that produced the error (for
example, CLI for the Command Language Interpreter).
l is a one letter code indicating the severity of the error.
The severities are:
I - Informational E - Error
S - Success F - Severe error
W - Warning
ident is an abbreviation for the message text.
text is a short description of the nature of the error.
Hints
Type the name of one of the categories listed below to obtain a list of related commands and topics. To obtain detailed information on a topic, press the RETURN key until you reach the "Topic?" prompt and then type the name of the topic. Topics that appear in all upper case are DCL commands.
Additional information available:
Batch and print jobsCommand proceduresContacting peopleCreating processes
Developing programsExecuting programsFiles and directoriesLogical names
Operators in expressionsPhysical devicesSystem managementTerminal environment
User environment
Batch and print jobs
Submitting batch and print jobs and controlling batch and print queues. ASSIGN/MERGE Moves jobs from one queue to another. ASSIGN/QUEUE Assigns a queue to a device. DEASSIGN/QUEUE Deassigns a queue from a device. DELETE/ENTRY Deletes a job or jobs from a queue. DELETE/QUEUE Deletes a queue and all its jobs. INITIALIZE/QUEUE Creates and initializes a queue. PRINT Places a job in a print queue. SET QUEUE Changes the current status or attributes of a queue. SET QUEUE/ENTRY Changes the attributes of a job. SHOW PRINTER Displays default characteristics defined for a printer. SHOW QUEUE Displays the attributes of the jobs in a queue. START/QUEUE Starts or restarts a queue. STOP/QUEUE Stops a queue. SUBMIT Places a job in a batch queue. SYNCHRONIZE Suspends processing until a specified job completes. Type ? to display the list of HINTS. Type BATCH_AND_PRINT_JOBS to redisplay this particular hint. Press the RETURN key before typing a command or topic name.
Command procedures
Performing operations specific to command procedures.
@ Describes how to invoke command procedures.
Lexical Describes functions that can be used in expressions.
Specify Describes valid values and expressions.
Symbol_Assign Describes symbol assigments statements.
CALL Transfers control to a labeled subroutine in a
command prodecure and creates a new procedure level.
DECK Marks the beginning of a special input stream.
DELETE/SYMBOL Deletes one or more names from a symbol table.
ENDSUBROUTINE Ends a CALL subroutine and returns control to the
command following the CALL command.
EOD Marks the end of a special input stream.
EXIT Terminates a command procedure.
GOSUB Transfers control to a labeled subroutine in a
command procedure.
GOTO Transfers control to a label in a command procedure.
IF Executes a command only if an expression is true.
INQUIRE Requests input and assigns the result to a symbol.
ON Specifies an action to perform when a condition occurs.
RETURN Terminates a GOSUB subroutine procedure and returns
control to the command following the calling GOSUB
command.
SET CONTROL Controls the use of the CTRL/T and CTRL/Y keys.
SET ON Sets error checking on or off.
SET RESTART_VALUE Sets the value of a batch job restart symbol.
SET VERIFY Displays command input as it is read.
SHOW SYMBOL Displays the value of a symbol.
SUBROUTINE Begins a CALL subroutine.
WAIT Suspends processing for a specified period of time.
OPEN Makes a file available for reading or writing.
CLOSE Terminates processing of a file.
READ Reads and optionally deletes a record from an open file.
WRITE Writes a record to an open file.
Type ? to display the list of HINTS.
Type COMMAND_PROCEDURES to redisplay this particular hint.
Press the RETURN key before typing a command or topic name.
Contacting people
Communicating with other people using the system.
MAIL Sends/reads messages to/from other users.
PHONE Permits users to communicate by typing messages to
one another's terminal screens.
REPLY Displays a message on one or more terminal screens.
REQUEST Displays a message on the operator's console.
SHOW USERS Lists the interactive users on the system.
Type ? to display the list of HINTS.
Type CONTACTING_PEOPLE to redisplay this particular hint.
Press the RETURN key before typing a command or topic name.
Creating processes
Create and switch control between user processes. (Also see Batch_and_print_jobs) Login Initiates an interactive terminal session. LOGOUT Terminates an interactive terminal session. SET PASSWORD Changes your password. ANALYZE/PROCESS Analyzes a process dump. ATTACH Switches your terminal between SPAWNed processes. CONNECT Connects a physical terminal to a virtual terminal. DISCONNECT Disconnects a physical terminal from a virtual terminal. PRINT Creates a print job. RUN/PROCESS Creates a detached process or subprocess. SET HOST Connects your terminal to another system via DECnet. SHOW NETWORK Displays the nodes you can reach from your system. SPAWN Creates a subprocess with a similar environment. SUBMIT Creates a batch job. Type ? to display the list of HINTS. Type CREATING_PROCESSES to redisplay this particular hint. Press the RETURN key before typing a command or topic name.
Developing programs
Creating and debugging images. (Also see Executing_programs and Files_and_directories) ANALYZE/IMAGE Analyzes an image file. ANALYZE/OBJECT Analyzes an object module. DEBUG Invokes the symbolic debugger after a CTRL/Y. DEPOSIT Changes the contents of memory. DIFFERENCES Displays differences in content between two files. DUMP Displays the uninterpreted contents of a file. EDIT Creates (optionally) and edits a file. EXAMINE Displays the contents of memory. LIBRARY Creates or modifies various kinds of libraries. LINK Creates images from object modules. MACRO Creates object modules from macro source programs. MESSAGE Creates object modules from message source programs. PATCH Patches an image. RUN Runs an executable image. SET COMMAND Updates the commands available to the process. Type ? to display the list of HINTS. Type DEVELOPING_PROGRAMS to redisplay this particular hint. Press the RETURN key before typing a command or topic name.
Executing programs
Running executable images.
(Also see Developing_programs and Files_and_directories)
CANCEL Cancels a scheduled wakeup request.
CONTINUE Resumes execution of an interrupted command.
DEBUG Invokes the VMS Debugger after a CTRL/Y.
DEPOSIT Changes the contents of memory.
EXAMINE Displays the contents of memory.
EXIT Terminates execution of an image or command procedure.
RUN Runs an image.
SET COMMAND Updates the commands available to the process.
STOP Abruptly terminates execution of an image, process, or
command procedure.
Type ? to display the list of HINTS.
Type EXECUTING_PROGRAMS to redisplay this particular hint.
Press the RETURN key before typing a command or topic name.
Files and directories
Saving and cataloging information on storage devices. (Also see Developing_programs and Executing_programs) APPEND Appends one file to another. COPY Creates a copy of an existing file or files. CREATE Creates a new file. DELETE Deletes a file or files. DIFFERENCES Displays differences in content between two files. DIRECTORY Displays the names of the files in a directory. EDIT Creates (optionally) and edits a file. MERGE Merges sorted files. PRINT Prints the contents of a file. PURGE Deletes old versions of a file or files. RENAME Recataloges an existing file. SEARCH Locates a character string within a file or files. SORT Sorts the data in a file. TYPE Displays the contents of a file. SET DEFAULT Changes the default device and directory. SHOW DEFAULT Displays the default device and directory. ANALYZE/RMS_FILE Analyzes the internal structure of a file. CONVERT Changes the attributes of a file. CONVERT/RECLAIM Reclaims unused space in an indexed file. CREATE/DIRECTORY Creates a new directory or subdirectory. CREATE/FDL Creates a new file with tailored attributes. DUMP Displays the uninterpreted contents of a file. EDIT/FDL Creates a file definition file. EDIT/SUM Updates a file with multiple files of edit commands. EXCHANGE Reformats files formatted by other operating systems. LIBRARY Creates or modifies various kinds of libraries. RUNOFF Formats one or more documents (text files). SET DIRECTORY Changes the characterisitcs of a directory. SET FILE Changes the characteristics of a file. SET PROTECTION Changes the protection of a file. SET PROTECT/DEF Changes the default protection given to files. SET RMS_DEFAULT Changes the default block and buffer count values. SHOW PROTECTION Displays the default protection. SHOW QUOTA Displays your quota of space on a disk volume. SHOW RMS_DEFAULT Displays the default block and buffer count values. UNLOCK Closes a file accidentally left open. Type ? to display the list of HINTS. Type FILES_AND_DIRECTORIES to redisplay this particular hint. Press the RETURN key before typing a command or topic name.
Logical names
Using higher-level names in place of device and file names. (Also see Physical_devices) ASSIGN Equates a logical name to an equivalence string. CREATE/NAME_TABLE Creates a logical name table. DEASSIGN Deletes a logical name. DEFINE Equates a logical name to an equivalence string. SHOW LOGICAL Displays logical names and their equivalencies. SHOW TRANSLATION Displays a logical name and its first equivalence. Type ? to display the list of HINTS. Type LOGICAL_NAMES to redisplay this particular hint. Press the RETURN key before typing a command or topic name.
Operators in expressions
Operands in an expression are connected by operators. If there is more
than one operator in an expression, the operator having the highest
precedence is evaluated first. If an expression contains operators that
have the same order of precedence, the operations are performed from
left to right. Use parentheses to override the normal order of
precedence.
Operator Precedence Description
+ 7 Indicates a positive number
-- 7 Indicates a negative number
* 6 Multiplies two numbers
/ 6 Divides two numbers
+ 5 Adds two numbers or concatenates two character
strings
-- 5 Subtracts two numbers or reduces a string
.EQS. 4 Tests if two character strings are equal
.GES. 4 Tests if first string is greater than or equal
to second
.GTS. 4 Tests if first string is greater than second
.LES. 4 Tests if first string is less than or equal to
second
.LTS. 4 Tests if first string is less than second
.NES. 4 Tests if two strings are not equal
.EQ. 4 Tests if two numbers are equal
.GE. 4 Tests if first number is greater than or equal
to second
.GT. 4 Tests if first number is greater than second
.LE. 4 Tests if first number is less than or equal
to second
.LT. 4 Tests if first number is less than second
.NE. 4 Tests if two numbers are not equal
.NOT. 3 Logically negates a number
.AND. 2 Combines two numbers with a logical AND
.OR. 1 Combines two numbers with a logical OR
Physical devices
Using physical devices. (Also see Logical_names, and Terminal_environment) ALLOCATE Allocates a device for your exclusive use. DEALLOCATE Releases an allocated device for general use. DISMOUNT Makes a storage device unavailable for processing. INITIALIZE Formats a storage device. MOUNT Makes a storage device available for processing. ANALYZE/DISK Checks the readability and validity of disks. ANALYZE/ERROR_LOG Displays the contents of the system error log. ANALYZE/MEDIA Analyzes the format of a storage device. BACKUP Saves or restores files from storage devices. SET CARD_READER Sets the translation mode for a card reader. SET DEVICE Sets device characteristics. SET MAGTAPE Sets magnetic tape device characteristics. SET PRINTER Sets line printer characteristics. SET PROTECT/DEV Sets protection on a non-files device. SET VOLUME Sets mounted volume characteristics. SHOW DEVICES Displays the status of devices. SHOW ERROR Displays device error counts. SHOW MAGTAPE Displays magnetic tape characteristics. SHOW PRINTER Displays line printer characteristics. Type ? to display the list of HINTS. Type PHYSICAL_DEVICES to redisplay this particular hint. Press the RETURN key before typing a command or topic name.
System management
Monitoring, maintaining, tuning, and trouble-shooting the system. (Also see Batch_and_print_jobs, Logical_names, and Physical_devices) ACCOUNTING Collects, records, and reports accounting information. ANALYZE/CRASH Analyzes a system dump. ANALYZE/DISK Checks the readability and validity of disks. ANALYZE/ERROR_LOG Displays the contents of the system error log. ANALYZE/MEDIA Analyzes the format of a storage device. ANALYZE/RMS_FILE Analyzes the internal structure of a file. ANALYZE/SYSTEM Analyzes the running system. BACKUP Saves or restores files from storage devices. MONITOR Displays performance information on the running system. REPLY Displays a message on one or more terminal screens. REQUEST Displays a message on the operator's console. SET ACCOUNTING Initializes the accounting log file. SET AUDIT Enables auditing of security events. SET COMMAND Updates the commands available to the system. SET DAY Changes the day type. SET LOGINS Sets a limit on the number of interactive users. SET TIME Resets the system clock. SHOW ERROR Displays processor, memory, and device error counts. SHOW MEMORY Displays usage information on memory. SHOW SYSTEM Lists the processes on the running system. SHOW USER Lists the interactive users on the running system. Type ? to display the list of HINTS. Type SYSTEM_MANAGEMENT to redisplay this particular hint. Press the RETURN key before typing a command or topic name.
Terminal environment
Manipulating your terminal-specific interactive environment (Also see Physical_devices) Line_editing Describes how to recall and edit commands. CONNECT Connects a physical terminal to a virtual terminal. DEFINE/KEY Equates terminal function keys to command lines. DELETE/KEY Deletes a terminal function key definition. DISCONNECT Disconnects a physical terminal from a virtual terminal. RECALL Recalls previously entered interactive commands. SET CONTROL Controls the use of the CTRL/T and CTRL/Y keys. SET HOST Connects your terminal to another system via DECnet. SET PROMPT Sets the interactive command prompt. SET TERMINAL Sets terminal characteristics. SHOW KEY Displays one or more function key definitions. SHOW TERMINAL Displays terminal characteristics. Type ? to display the list of HINTS. Type TERMINAL_ENVIRONMENT to redisplay this particular hint. Press the RETURN key before typing a command or topic name.
User environment
Examining and controling the user environment. (Also see Logical_names, Physical_devices, and Terminal_environment) SET COMMAND Updates the commands available to the process. SET CONTROL Controls the use of the CTRL/T and CTRL/Y keys. SET DEFAULT Changes the default device and directory. SET HOST Connects your terminal to another system via DECnet. SET MESSAGE Overrides or supplements system messages. SET PASSWORD Changes your password. SET PROCESS Changes your process characteristics. SET PROMPT Sets the interactive command prompt. SET PROTECT/DEF Changes the default protection given to files. SET RMS_DEFAULT Changes the default block and buffer count values. SET UIC Changes the UIC of your process. SET WORKING_SET Changes your working set limit or quota. SHOW DEFAULT Displays the default device and directory. SHOW KEY Displays one or more function key definitions. SHOW LOGICAL Displays logical names and their equivalencies. SHOW PROCESS Displays your process characteristics. SHOW PROTECTION Displays the default protection. SHOW QUOTA Displays your quota of space on a disk volume. SHOW RMS_DEFAULT Displays the default block and buffer count values. SHOW STATUS Displays brief process characteristics. SHOW SYMBOL Displays the value of a symbol. SHOW TERMINAL Displays terminal characteristics. SHOW TIME Displays the current date and time. SHOW TRANSLATION Displays a logical name and its first equivalence. SHOW WORKING_SET Displays your working set limit and quota. Type ? to display the list of HINTS. Type USER_ENVIRONMENT to redisplay this particular hint. Press the RETURN key before typing a command or topic name.
Instructions
Invoking the HELP utility ------------------------- The HELP utility displays information about requested VMS topics. From DCL command level (in response to the $ prompt), you can display a list of topics for which help information is available by typing HELP and pressing the RETURN key. The system responds by displaying a brief description of how to use HELP, followed by a list of topics for which help is available, followed by the prompt "Topic?". You can exit from the HELP facility by typing CTRL/Z (that is, pressing the CONTROL and Z keys simultaneously) in response to any prompt. Specifying topic names ---------------------- To display information on a particular topic, respond to the prompt by typing the name of the topic and pressing the RETURN key. If you are not sure of the name of the topic for which you need help, type the name HINTS. To display information on all available topics, type an asterisk (*). To display all the information on a topic, type the topic name immediately follwed by an ellipsis (...), e.g., SHOW... You can specify percent signs (%) and asterisks (*) in the keyword as wild card (i.e., match all) characters. Abbreviations result in all matches being displayed. Subtopic information -------------------- The information displayed by HELP on a particular topic includes a description of the topic and a list of subtopics that further describe the topic. To display subtopic information, type one of the subtopic names from the list in response to the "Subtopic?" prompt. Special responses to prompts ---------------------------- If you press RETURN in response to the "Subtopic?" prompt instead of typing a subtopic name, the "Topic?" prompt reappears, enabling you to enter another topic name. If you press RETURN in response to the "Topic?" prompt, you will exit from HELP. You can type a question mark (?) in response to any of the prompts to to redisplay the most recently requested text and a list of topic or subtopic names. For example, if you type ? in response to the "Subtopic?" prompt, a list of subtopics is displayed followed by the "Subtopic?" prompt.
Lexicals
A set of functions that return information about character strings and attributes of the current process.
Additional information available:
F$CONTEXTF$CSIDF$CVSIF$CVTIMEF$CVUIF$DEVICE
F$DIRECTORYF$EDITF$ELEMENTF$ENVIRONMENT
F$EXTRACTF$FAOF$FILE_ATTRIBUTESF$GETDVIF$GETJPI
F$GETQUIF$GETSYIF$IDENTIFIERF$INTEGERF$LENGTHF$LOCATE
F$MESSAGEF$MODEF$PARSEF$PIDF$PRIVILEGE
F$PROCESSF$SEARCHF$SETPRVF$STRINGF$TIMEF$TRNLNMF$TYPE
F$USERF$VERIFY
F$CONTEXT
Specifies selection criteria for use with the F$PID function.
The F$CONTEXT function enables the F$PID function to obtain
information about processes from any node in a VAXcluster.
Format
F$CONTEXT(context-type, context-symbol, selection-item,
selection-value, value-qualifier)
Additional information available:
Return Valuecontext-typecontext-symbolselection-itemselection-value
value-qualifierExample
Return Value
A null string ("").
context-type
Specifies the type of context to be built. At present, the only context type available is PROCESS, which is used in constructing selection criteria for F$PID.
context-symbol
Specifies a symbol that DCL uses to refer to the context memory being constructed by the F$CONTEXT function. The function F$PID uses this context symbol to process the appropriate list of process identification (PID) numbers. Specify the context symbol by using a symbol. The first time you use the F$CONTEXT function in a command procedure, use a symbol that is either undefined or equated to the null string. The symbol created will be a local symbol of type "PROCESS_CONTEXT". When the context is no longer valid-that is, when all PIDs have been retrieved by calls to the F$PID function or an error occurs during one of these calls-the symbol no longer has a type of "PROCESS_ CONTEXT". Then you can use the F$TYPE function in the command procedure to find out if it is necessary to cancel the context. After setting up the selection criteria, use this context symbol when calling F$PID.
selection-item
Specifies a keyword that tells F$CONTEXT which selection criteria
to use. Use only one selection-item keyword per call to F$CONTEXT.
The following table shows valid selection-item keywords for the
PROCESS context type:
Selection SelectionValue
Item Value Qualifiers Comments
ACCOUNT String EQL, NEQ Valid account name or list of
names. Wildcard characters (* and
%) are allowed.
AUTHPRI Integer GEQ, GTR, Valid authorized base priority
LEQ, LSS, (0-31).
EQL, NEQ
CANCEL Cancels the selection criteria for
this context.
CURPRIV Keyword ALL, ANY, Valid privilege name keyword
EQL, NEQ or list of keywords. For more
information, see the VMS DCL
Concepts Manual.
GRP String GEQ, GTR, Group number or name.
LEQ, LSS,
EQL, NEQ
HW_MODEL Integer EQL, NEQ Valid hardware model number.
HW_NAME String EQL, NEQ Valid hardware name or a list
of keywords. Wildcard characters
(* and %) are allowed.
JOBPRCCNT Integer GEQ, GTR, Subprocess count for entire job.
LEQ, LSS,
EQL, NEQ
JOBTYPE Keyword EQL, NEQ Valid job-type keyword. Valid
keywords are DETACHED, NETWORK,
BATCH, LOCAL, DIALUP, and REMOTE.
For more information, see the VMS
DCL Concepts Manual.
MASTER_PID String EQL, NEQ PID of master process.
MEM String GEQ, GTR, UIC member number or name.
or LEQ, LSS,
Integer EQL, NEQ
MODE Keyword EQL, NEQ Valid process mode keyword. Valid
keywords are OTHER, NETWORK,
BATCH, and INTERACTIVE. For
more information, see the VMS
DCL Concepts Manual.
NODE_CSID Integer EQL, NEQ Node's cluster ID number.
NODENAME String EQL, NEQ Node name or list of node names.
Wildcard characters are allowed.
The default is your local node. To
request all nodes, use the value
"*".
OWNER String EQL, NEQ PID of immediate parent process.
PRCCNT Integer GEQ, GTR, Subprocess count of process.
LEQ, LSS,
EQL, NEQ
PRCNAM String EQL, NEQ Process name or list of process
names. Wildcard characters are
allowed.
PRI Integer GEQ, GTR, Process priority level number
LEQ, LSS, (0-31).
EQL, NEQ
PRIB Integer GEQ, GTR, Base process priority level number
LEQ, LSS, (0-31).
EQL, NEQ
STATE Keyword EQL, NEQ Valid process state keyword.
For more information, see the
description of the $GETJPI
service in the VMS System Services
Reference Manual.
STS Keyword EQL, NEQ Valid process status keyword.
For more information, see the
description of the $GETJPI
service in the VMS System Services
Reference Manual.
TERMINAL String EQL, NEQ Terminal name or list of names.
Wildcard characters are allowed.
UIC String EQL, NEQ User identification code (UIC)
identifier (that is, of the form
"[group,member]").
USERNAME String EQL, NEQ User name or list of user names.
Wildcard characters (* and %) are
allowed.
selection-value
Specifies the value of the selection criteria. For example, to
process all the processes running on node MYVAX, specify "MYVAX"
with the "NODENAME" keyword. For example:
$ X = F$CONTEXT("PROCESS", ctx, "NODENAME", "MYVAX", "EQL")
Values that are lists are valid with some selection items. If you
specify more than one item, separate them with commas (,). The
following example specifies a list of the nodes MYVAX, HERVAX, and
HISVAX:
$ X = F$CONTEXT("PROCESS", ctx, "NODENAME", "MYVAX,HERVAX,HISVAX", "EQL")
You can use wildcard characters (* and %) for some values. Using
wildcard characters for selection items is similar to using
wildcard characters for file names.
value-qualifier
Specifies qualifiers for selection values. You must qualify selection values. You can qualify a number, for example, by requesting that the selection be based on the process value less than (LSS), less than or equal to (LEQ), greater than (GTR), greater than or equal to (GEQ), equal to (EQL), or not equal to (NEQ) the value specified in the call to F$PID. You can qualify some lists with the ALL, ANY, EQL, or NEQ keywords. Such lists are usually masks such as the process privilege mask, which consists of the set of enabled privileges. ALL requires that all items in the list be true for a process; ANY requests that any item in the list be part of the attributes of a process; EQL means that the values must match exactly (that is, values not specified must not be true of the process); and NEQ requires that the value must not match. The difference between ALL and EQL is that the values specified with ALL must exist, but other unspecified values can exist also. EQL requires that all values specified must exist, and all others may not. For example, to request those processes whose current privileges include TMPMBX (temporary mailbox) and OPER (operator), but may include other privileges, specify the ALL keyword. To request those processes whose current privileges are TMPMBX and OPER exclusively, specify the EQL keyword.
Example
$!Establish an error and CTRL/Y handler
$!
$ ON ERROR THEN GOTO error
$ ON CONTROL_Y THEN GOTO error
$!
$ ctx = ""
$ temp = F$CONTEXT ("PROCESS", ctx, "NODENAME", "*","EQL")
$ temp = F$CONTEXT ("PROCESS", ctx, "USERNAME", "M*,SYSTEM","EQL")
$ temp = F$CONTEXT ("PROCESS", ctx, "CURPRIV", "SYSPRV,OPER", "ALL")
$!
$!Loop over all processes that meet the selection criteria.
$!Print the PID and the name of the image for each process.
$!
$loop:
$ pid = F$PID(ctx)
$ IF pid .EQS. ""
$ THEN
$ GOTO endloop
$ ELSE
$ image = F$GETJPI(pid,"IMAGNAME")
$ SHOW SYMBOL pid
$ WRITE SYS$OUTPUT image
$ GOTO loop
$ ENDIF
$!The loop over the processes has ended.
$!
$endloop:
$!
$ EXIT
$!
$!Error handler. Clean up the context's memory with
$!the CANCEL selection item keyword.
$!
$error:
$ IF F$TYPE(ctx) .eqs. "PROCESS_CONTEXT" THEN -
-$ temp = F$CONTEXT ("PROCESS", ctx, "CANCEL")
$!
$ EXIT
In this example, F$CONTEXT is called three times to set up
selection criteria. The first call requests that the search
take place on all nodes in the cluster. The second call
requests that only the processes whose user name either
starts with an "M" or is "SYSTEM" be processed. The third
call restricts the selection to those processes whose current
privileges include both SYSPRV (system privilege) and OPER
(operator) and can have other privileges set.
The command lines between the labels "loop" and "endloop"
continually call F$PID to obtain the processes that meet the
criteria set up in the F$CONTEXT calls. After retrieving each
PID, F$GETJPI is called to return the name of the image running
in the process. Finally, the procedure displays the name of the
image.
In case of error or a CTRL/Y operation, control is passed to
error and the context is closed if necessary. In this example,
note the check for the symbol type PROCESS_CONTEXT. If the
symbol has this type, selection criteria must be canceled by
a call to F$CONTEXT. If the symbol is not of the type PROCESS_
CONTEXT, either selection criteria have not been set up yet
in F$CONTEXT, or the symbol has been used with F$PID until
an error occurred or until the end of the process list was
reached.
F$CSID
Returns a cluster identification number, and updates the context
symbol to point to the current position in the system's cluster
node list.
Format
F$CSID(context-symbol)
Additional information available:
Return Valuecontext-symbolDescriptionExample
Return Value
A character string containing the system cluster identification
number in the system's list of clustered nodes. If the current
system is not a member of a cluster, the first return value is
null.
After the last system name is returned, the F$CSID function
returns a null string ("").
context-symbol
Specifies a symbol that DCL uses to store a pointer into the
system's list of clustered nodes. The F$CSID function uses this
pointer to return a cluster node name.
Specify the context-symbol argument by using a symbol. The first
time you use the F$CSID function, use a symbol that is either
undefined or equated to the null string ("").
If the context-symbol argument is undefined or equated to a
null string, the F$CSID function returns the first system in
the system's cluster node list. Subsequent calls to the F$CSID
function will give the rest of the nodes in the cluster.
Description
The F$CSID function returns a cluster identification number, and updates the context symbol to point to the current position in the system's cluster node list. If the current system is not a member of a cluster, the first return value is null. You can use the F$CSID function to obtain all of the cluster id numbers on the system. For each cluster id returned, the F$GETSYI function can be used to obtain information about the particular system. Once the context-symbol argument is initialized by the first call, each subsequent F$CSID function call returns another node in the cluster. (Note that the cluster identification numbers are returned in random order.) After the last cluster system in the list is returned, the F$CSID function returns a null string.
Example
$ IF F$GETSYI("CLUSTER_MEMBER") .EQS. "FALSE" THEN GOTO NOT_CLUSTER
$ CONTEXT = ""
$START:
$ id = F$CSID (CONTEXT)
$ IF id .EQS. "" THEN EXIT
$ nodename = F$GETSYI ("NODENAME",,id)
$ WRITE SYS$OUTPUT nodename
$ GOTO start
$NOT_CLUSTER:
$ WRITE SYS$OUTPUT "Not a member of a cluster."
$ EXIT
This command procedure uses the F$CSID function to display
a list of cluster system names. The assignment statement
declares the symbol CONTEXT, which is used as the context-
symbol argument for the F$CSID function. Because CONTEXT is
equated to a null string, the F$CSID function will return the
first cluster identification number in the cluster node list.
If the F$CSID function returns a null value, then the command
procedure is either at the end of the list, or is attempting
this operation on a non-clustered node. The call to F$GETSYI
checks whether the current node is a member of a cluster. The
command procedure will exit on this condition.
If the F$CSID function does not return a null value, then the
command procedure uses the identification number as the third
argument to the F$GETSYI function to obtain the name of the
system. The name is then displayed using the WRITE command.
F$CVSI
Converts the specified bits in the specified character string to a
signed number.
Format
F$CVSI(start-bit,number-of-bits,string)
Additional information available:
Return Valuestart-bitnumber-of-bitsstringExample
Return Value
The integer equivalent of the extracted bit field, converted as a signed value.
start-bit
Specifies the offset of the first bit to be extracted. The low-order (rightmost) bit of a string is position number 0 for determining the offset. Specify the offset as an integer expression. If you specify an expression with a negative value, or with a value that exceeds the number of bits in the string, then DCL displays the INVRANGE error message.
number-of-bits
Specifies the length of the bit string to be extracted, which must be less than or equal to the number of bits in the string. If you specify an expression with a negative value, or with a value that is invalid when added to the bit position offset, then DCL displays the INVRANGE error message.
string
Specifies the string from which the bits are taken. Specify the string as a character string expression.
Example
$ A[0,32] = %X2B
$ SHOW SYMBOL A
A = "+..."
$ X = F$CVSI(0,4,A)
$ SHOW SYMBOL X
X = -5 Hex = FFFFFFFB Octal = 37777777773
This example uses an arithmetic overlay to assign the
hexadecimal value 2B to all 32 bits of the symbol A. For more
information on arithmetic overlays, see the description of the
assignment statement (=).
The symbol A has a string value after the overlay because it
was previously undefined. (If a symbol is undefined, it has a
string value as a result of an arithmetic overlay. If a symbol
was previously defined, it retains the same data type after
the overlay.) The hexadecimal value 2B corresponds to the ASCII
value of the plus sign (+).
Next, the F$CVSI function extracts the low-order 4 bits
from the symbol A; the low-order 4 bits contain the binary
representation of the hexadecimal value B. These bits are
converted, as a signed value, to an integer. The converted
value, -5, is assigned to the symbol X.
F$CVTIME
Converts an absolute or a combination time string to a string of
the form yyyy-mm-dd hh:mm:ss.cc. The F$CVTIME function can also
return information about an absolute, combination, or delta time
string.
Format
F$CVTIME([input_time] [,output_time_format] [,output_field])
Additional information available:
Return Valueinput timeoutput time formatoutput fieldDescriptionExamples
Return Value
A character string containing the requested information.
input time
Specifies a string containing an absolute, combination, or delta
time, or TODAY, TOMORROW, or YESTERDAY. Specify the input time
string as a character string expression. If the input_time
argument is omitted or is specified as a null string (""), the
current system date and time, in absolute format, is used. If
parts of the date field are omitted, the missing values default
to the current date. If parts of the time field are omitted, the
missing values default to zero.
For more information on these time formats, see the VMS DCL
Concepts Manual.
If the input_time argument is a delta time, you must specify the
output_time_format argument as DELTA.
output time format
Specifies the time format for the information you want returned.
Specify the output_time_format argument as one of the following
character string expressions:
ABSOLUTE The requested information should be returned
in absolute time format, which is dd-mmm-yyyy
hh:mm:ss.cc.
COMPARISON The requested information should be returned in the
(default) form yyyy-mm-dd hh:mm:ss.cc; used for comparing two
times.
DELTA The requested information should be returned
in delta format, which is dddd-hh:mm:ss.cc. If
you specify DELTA as the output_time_format
argument, then you must also provide a delta time
specification for the input_time argument.
output field
Specifies a character string expression containing one of the following (do not abbreviate): DATE, MONTH, DATETIME (default), SECOND, DAY, TIME, HOUR, WEEKDAY, HUNDREDTH, YEAR, MINUTE. The information is returned in the time format specified by the output_time_format argument. If the input_time argument is a delta time and the output_time_format argument is DELTA, you cannot specify MONTH, WEEKDAY, or YEAR. When the weekday is returned, the first letter is in uppercase, and the following letters are in lowercase.
Description
When using the F$CVTIME function, you can omit optional arguments that can be used to the right of the last argument you specify. However, you must include commas (,) as placeholders if you omit optional arguments to the left of the last argument you specify. When specifying the input time argument in either absolute or combination time format, you can specify ABSOLUTE or COMPARISON as the output_time_format argument; you cannot specify DELTA. When specifying the input_time argument in delta time format, you must specify DELTA as the output_time_format argument.
Examples
1. $ TIME = F$TIME()
$ SHOW SYMBOL TIME
TIME = "19-APR-1990 10:56:23.10"
$ TIME = F$CVTIME(TIME)
$ SHOW SYMBOL TIME
TIME = "1990-04-19 10:56:23.10"
This example uses the F$TIME function to return the system
time as a character string and to assign the time to the symbol
TIME. Then the F$CVTIME function is used to convert the system
time to an alternate time format. Note that you do not need to
place quotation marks (" ") around the argument TIME because it
is a symbol. Symbols are automatically evaluated when they are
used as arguments for lexical functions.
You can use the resultant string to compare two dates (using
.LTS. and .GTS. operators). For example, you can use F$CVTIME
to convert two time strings and store the results in the
symbols TIME_1 and TIME_2. You can compare the two values, and
branch to a label, based on the following results:
$ IF TIME_1 .LTS. TIME_2 THEN GOTO FIRST
2. $ NEXT = F$CVTIME("TOMORROW",,"WEEKDAY")
$ SHOW SYMBOL NEXT
NEXT = "Tuesday"
In this example, the F$CVTIME returns the weekday that
corresponds to the absolute time keyword "TOMORROW". You must
enclose the arguments "TOMORROW" and "WEEKDAY" in quotation
marks because they are character string expressions. Also,
you must include a comma as a placeholder for the output time
argument that is omitted.
F$CVUI
Extracts bit fields from character string data and converts the
result to an unsigned number.
Format
F$CVUI(start-bit,number-of-bits,string)
Additional information available:
Return Valuestart-bitnumber-of-bitsstringExample
Return Value
The integer equivalent of the extracted bit field, converted as an unsigned value.
start-bit
Specifies the offset of the first bit to be extracted. The low-order (rightmost) bit of a string is position number 0 for determining the offset. Specify the offset as an integer expression. If you specify an expression with a negative value, or with a value that exceeds the number of bits in the string, DCL displays the INVRANGE error message.
number-of-bits
Specifies the length of the bit string to be extracted, which must be less than or equal to the number of bits in the string argument. If you specify an expression with a negative value, or with a value that is invalid when added to the bit position offset, DCL displays the INVRANGE error message.
string
Specifies the character string to be edited.
Example
$ A[0,32] = %X2B
$ SHOW SYMBOL A
A = "+..."
$ X = F$CVUI(0,4,A)
$ SHOW SYMBOL X
X = 11 Hex = 0000000B Octal = 00000000013
This example uses an arithmetic overlay to assign the
hexadecimal value 2B to all 32 bits of the symbol A. The
symbol A has a string value after the overlay because it was
previously undefined. (If a symbol is undefined, it has a
string value as a result of an arithmetic overlay. If a symbol
was previously defined, it retains the same data type after
the overlay.) The hexadecimal value 2B corresponds to the ASCII
character "+".
Next, the F$CVUI function extracts the low-order 4 bits
from the symbol A; the low-order 4 bits contain the binary
representation of the hexadecimal value B. These bits are
converted, as a signed value, to an integer. The converted
value, 11, is assigned to the symbol X.
F$DEVICE
Returns the device names of all devices on a system that meet the
specified selection criteria.
Note that the device names are returned in random order.
Format
F$DEVICE([search_devnam],[devclass],[devtype],[stream-id])
Additional information available:
Return Valuesearch devnamdevclassdevtypestream-idExample
Return Value
A character string containing the name of a device in the system's
list of devices.
After the last device name in the system's device list is
returned, the F$DEVICE function returns a null string ("").
search devnam
Name of the device for which F$DEVICE is to search. Wildcard characters (* and %) are allowed in the search_devnam argument. Specify the search_devnam argument as a character string expression.
devclass
Selects the device class for which F$DEVICE is to search. Specify the devclass argument as a character string expression that corresponds to a valid device class name.
devtype
Selects the device type for which F$DEVICE is to search. Specify
the devtype argument as a character string expression that
corresponds to a valid type name.
NOTE
Specifying a device type without specifying a device class
will result in an error.
stream-id
A positive integer representing the search stream identification number. The search stream identification number is used to maintain separate search contexts when you use the F$DEVICE function more than once and when you supply different search criteria. If you use the F$DEVICE function more than once in a command procedure and if you also used different search criteria, specify stream-id arguments to identify each search separately. If the search criteria are changed in a call before the device name list is exhausted, the context will be reinitialized and the search will restart. If you omit the stream-id argument, the F$DEVICE function assumes an implicit single search stream. That is, the F$DEVICE function starts searching at the beginning each time you specify different search criteria.
Example
$ START:
$ DEVICE_NAME = F$DEVICE("*0","DISK","RA60")
$ IF DEVICE_NAME .EQS. "" THEN EXIT
$ SHOW SYMBOL DEVICE_NAME
$ GOTO START
This command procedure displays the device names of all the
RA60s on a unit numbered 0.
Because no stream-id argument is specified, F$DEVICE uses an
implicit search stream. Each subsequent use of the F$DEVICE
function uses the same search criteria to return the next
device name. After the last device name is displayed, the
F$DEVICE function returns a null string and the procedure
exits.
F$DIRECTORY
Returns the current default directory name string. The F$DIRECTORY
function has no arguments, but must be followed by parentheses.
Format
F$DIRECTORY()
Additional information available:
Return Value
A character string for the current default directory name, including square brackets ([]). If you use the SET DEFAULT command and specify angle brackets (<>) in a directory specification, the F$DIRECTORY function returns angle brackets in the directory string.
Example
$ SAVE_DIR = F$DIRECTORY()
$ SET DEFAULT [MALCOLM.TESTFILES]
.
.
.
$ SET DEFAULT 'SAVE_DIR'
This example shows an excerpt from a command procedure that
uses the F$DIRECTORY function to save the current default
directory setting. The assignment statement equates the symbol
SAVE_DIR to the current directory. Then the SET DEFAULT command
establishes a new default directory. Later, the symbol SAVE_DIR
is used in the SET DEFAULT command that restores the original
default directory.
Note that you can use the F$ENVIRONMENT function with the
DEFAULT keyword to return the default disk and directory.
You should use the F$ENVIRONMENT function rather than the
F$DIRECTORY function in situations involving more than one
disk.
F$EDIT
Edits the character string based on the edits specified in the
edit-list argument.
Format
F$EDIT(string, edit-list )
Additional information available:
Return Valuestringedit-listExamples
Return Value
A character string containing the specified edits.
string
Specifies a character string to be edited. Quoted sections of the string are not edited.
edit-list
Specifies a character string containing one or more of the
following keywords which specify the types of edits to be made
to the string. If you specify more than one keyword, separate them
with commas (,). Do not abbreviate these keywords.
Edit Action
COLLAPSE Removes all spaces or tabs.
COMPRESS Replaces multiple spaces or tabs with a single
space.
LOWERCASE Changes all uppercase characters to lowercase.
TRIM Removes leading and trailing spaces or tabs.
UNCOMMENT Removes comments.
UPCASE Changes all lowercase characters to uppercase.
Edits are not applied to quoted sections of strings. Therefore,
if a string contains quotation marks (" "), the characters within
the quotation marks are not affected by the edits specified in the
edit list.
Examples
1. $ LINE = " THIS LINE CONTAINS A "" QUOTED "" WORD"
$ SHOW SYMBOL LINE
LINE = " THIS LINE CONTAINS A " QUOTED " WORD"
$ NEW_LINE = F$EDIT(LINE, "COMPRESS, TRIM")
$ SHOW SYMBOL NEW_LINE
NEW_LINE = "THIS LINE CONTAINS A " QUOTED " WORD"
This example uses the F$EDIT function to compress and trim a
string by replacing multiple blanks with a single blank, and by
removing leading and trailing blanks. The string LINE contains
quotation marks around the word QUOTED. (To enter quotation
marks into a character string, use double quotation marks in
the assignment statement.)
Note that the F$EDIT function does not compress the spaces in
the quoted section of the string; therefore, the spaces are
retained around the word QUOTED.
2. $ LOOP:
$ READ/END_OF_FILE = DONE INPUT_FILE RECORD
$ RECORD = F$EDIT(RECORD, "TRIM, UPCASE")
$ WRITE OUTPUT_FILE RECORD
$ GOTO LOOP
.
.
.
This example sets up a loop to read records from a file, to
edit them, and to write them to an output file. The edited
records have leading and trailing blanks removed, and are
converted to uppercase.
F$ELEMENT
Extracts one element from a string of elements.
Format
F$ELEMENT(element-number, delimiter, string)
Additional information available:
Return Valueelement-numberdelimiterstringExamples
Return Value
A character string containing the specified element.
element-number
Specifies the number of the element to extract (numbering begins with zero). Specify the element-number argument as an integer expression. If the element-number argument exceeds the number of elements in the string, F$ELEMENT returns the delimiter.
delimiter
Specifies a character used to separate the elements in the string. Specify the delimiter as a character string expression.
string
Specifies a string containing a delimited list of elements. Specify the string as a character string expression.
Examples
1. $ DAY_LIST = "MON/TUE/WED/THU/FRI/SAT/SUN"
$ INQUIRE DAY "ENTER DAY (MON TUE WED THU FRI SAT SUN)"
$ NUM = 0
$ LOOP:
$ LABEL = F$ELEMENT(NUM,"/",DAY_LIST)
$ IF LABEL .EQS. "/" THEN GOTO END
$ IF DAY .EQS. LABEL THEN GOTO 'LABEL'
$ NUM = NUM +1
$ GOTO LOOP
$
$ MON:
.
.
.
This example sets up a loop to test an input value against the
elements in a list of values. If the value for DAY matches
one of the elements in DAY_LIST, control is passed to the
corresponding label. If the value returned by the F$ELEMENT
function matches the delimiter, the value DAY was not present
in the DAY_LIST, and control is passed to the label END.
2. $ ! INDEX.COM
$ !
$ CHAPTERS = "0,1,2,3,4,5,6,A,B,C"
$ NEXT = 0
$ LOOP:
$ NEXT = NEXT + 1
$ NUM = F$ELEMENT(NEXT,",",CHAPTERS)
$ IF (NUM .NES. ",")
$ THEN
$ RUN INDEX CHAP'NUM'
$ GOTO LOOP
$ ENDIF
This example processes files named CHAP1, CHAP2, ... CHAP6,
CHAPA, CHAPB, and CHAPC, in that order. (Zero is included in
the CHAPTERS string to initialize the procedure logic.) NEXT
is initialized to zero. The procedure enters the loop. In the
first iteration, NEXT is incremented to 1 and the result of the
F$ELEMENT call is the string "1". The procedure runs the index,
chapter 1. In the second iteration, NEXT is incremented to 2
and the result of the F$ELEMENT call is the string "2". The
procedure runs the index, chapter 2. Processing continues until
the result of the F$ELEMENT call is the delimiter specified in
the call.
F$ENVIRONMENT
Returns information about the current DCL command environment.
Format
F$ENVIRONMENT(item)
Additional information available:
Return Value
Information that corresponds to the specified item. The return value can be either an integer or a character string, depending on the specified item.
item
Specifies the type of information to be returned.
Specify one of the following keywords (Do not abbreviate):
Data
Item Type Information Returned
CAPTIVE String TRUE if you are logged in to a
captive account. The system manager
can define captive accounts in
the user authorization file (UAF)
by using the Authorize Utility
(AUTHORIZE).
CONTROL String Control characters currently enabled
with SET CONTROL. Multiple characters
are separated by commas; if no
control characters are enabled, the
null string ("") is returned.
DEFAULT String Current default device and directory
name. The returned string is the same
as SHOW DEFAULT output.
DEPTH Integer Current command procedure depth. The
command procedure depth is 0 when
you log in interactively and when
you submit a batch job. The command
procedure depth is 1 when you execute
a command procedure interactively
or from within a batch job. A nested
command procedure has a depth of
1 greater than the depth of the
command procedure from which the
nested procedure is executed.
DISIMAGE String TRUE if you are logged in to an
account that does not allow the
use of the RUN and MCR commands or
foreign commands. The system manager
can add or remove the DISIMAGE
attribute for accounts in the UAF
by using AUTHORIZE.
INTERACTIVE String TRUE if the process is executing
interactively.
KEY_STATE String Current locked keypad state. See
the description of the DEFINE/KEY
command for more information on
keypad states.
MAX_DEPTH Integer Maximum allowable command procedure
depth.
MESSAGE String Current setting of SET MESSAGE
qualifiers. Each qualifier in
the string is prefaced by a slash
(/); therefore, the output from
F$ENVIRONMENT("MESSAGE") can be
appended to the SET MESSAGE command
to form a valid DCL command line.
NOCONTROL String Control characters currently
disabled with SET NOCONTROL. Multiple
characters are separated by commas
(,); if no control characters
are disabled, the null string is
returned.
ON_CONTROL_Y String If issued from a command procedure,
returns TRUE if ON_CONTROL_Y is set.
ON_CONTROL_Y always returns FALSE at
DCL command level.
ON_SEVERITY String If issued from a command procedure,
returns the severity level at which
the action specified with the ON
command is performed. ON_SEVERITY
returns NONE when SET NOON is in
effect or at DCL command level.
OUTPUT_RATE String Delta time string containing the
default output rate, which indicates
how often data is written to the
batch job log file while the batch
job is executing. OUTPUT_RATE returns
a null string if used interactively.
PROCEDURE String File specification of the current
command procedure. If used
interactively, the terminal device
name is returned.
PROMPT String Current DCL prompt.
PROMPT_CONTROL String TRUE if a carriage return and line
feed precede the prompt.
PROTECTION String Current default file protection.
The string can be used with the SET
PROTECTION/DEFAULT command to form a
valid DCL command line.
RESTRICTED String TRUE if you are logged into a
restricted account. The system
manager can define restricted
accounts in the UAF by using
AUTHORIZE.
SYMBOL_SCOPE String [NO]LOCAL, [NO]GLOBAL to indicate the
current symbol scoping state.
VERB_SCOPE String [NO]LOCAL,[NO]GLOBAL to indicate the
current verb substitution scoping
state.
VERIFY_IMAGE String TRUE if image verification (SET
VERIFY=IMAGE) is in effect. If image
verification is in effect, then the
command procedure echoes input data
read by images.
VERIFY_PREFIX String Returns the prefix control string set
by means of the SET PREFIX command.
VERIFY_PROCEDURE String TRUE if procedure verification
SET VERIFY=PROCEDURE is in effect. If
command verification is in effect,
then the command procedure echoes DCL
command lines.
Examples
1. $ SAVE_MESSAGE = F$ENVIRONMENT("MESSAGE")
$ SET MESSAGE/NOFACILITY/NOIDENTIFICATION
.
.
.
$ SET MESSAGE'SAVE_MESSAGE'
This example uses the F$ENVIRONMENT function to save the
current message setting before changing the setting. At the
end of the command procedure, the original message setting is
restored. The single quotation marks (' ') surrounding the
symbol SAVE_MESSAGE indicate that the value for the symbol
should be substituted.
2. $ MAX = F$ENVIRONMENT("MAX_DEPTH")
$ SHOW SYMBOL MAX
MAX = 32 Hex = 00000020 Octal = 00000000040
This example uses the F$ENVIRONMENT function to determine the
maximum depth allowable within command procedures.
3. $ SAVE_PROT = F$ENVIRONMENT("PROTECTION")
$ SET PROTECTION = (SYSTEM:RWED, OWNER:RWED, GROUP, WORLD)/DEFAULT
.
.
.
$ SET PROTECTION = ('SAVE_PROT')/DEFAULT
This example uses the F$ENVIRONMENT function to save the
current default protection before changing the protection.
At the end of the command procedure, the original protection
is restored. You must place single quotation marks around the
symbol SAVE_PROT to request symbol substitution.
F$EXTRACT
Extracts the specified characters from the specified string.
Format
F$EXTRACT(start,length,string)
Additional information available:
Return ValuestartlengthstringExamples
Return Value
A character string containing the characters delimited by the start and length arguments.
start
Specifies the offset of the starting character of the string
you want to extract. Specify the start argument as an integer
expression that is greater than or equal to zero.
The offset is the relative position of a character or a substring
with respect to the beginning of the string. Offset positions
begin with zero. The string always begins with the leftmost
character.
If you specify an offset that is greater than or equal to the
length of the string, F$EXTRACT returns a null string ("").
length
Specifies the number of characters you want to extract; must be less than or equal to the size of the string. Specify the length as an integer expression that is greater than or equal to zero. If you specify a length that exceeds the number of characters from the offset to the end of the string, the F$EXTRACT function returns the characters from the offset through the end of the string.
string
Specifies the character string to be edited. Specify the string as a character string expression.
Examples
1. $ NAME = "JOE SMITH"
$ FIRST = F$EXTRACT(0,3,NAME)
$ SHOW SYMBOL FIRST
FIRST = "JOE"
This portion of a command procedure uses the F$EXTRACT function
to extract the first 3 characters from the character string
assigned to the symbol NAME. The offset and length arguments
are integers, and the string argument is a symbol. You do not
need to use quotation marks (" ") around integers or symbols
when they are used as arguments for lexical functions.
2. $ P1 = "MYFILE.DAT"
$ FILENAME = F$EXTRACT(0,F$LOCATE(".",P1),P1)
This portion of a command procedure shows how to locate a
character within a string, and how to extract a substring
ending at that location.
The lexical function F$LOCATE gives the numeric value
representing the offset position of a period in the character
string value of P1. (The offset position of the period is equal
to the length of the substring before the period.)
This F$LOCATE function is used as an argument in the F$EXTRACT
function to specify the number of characters to extract from
the string. If a procedure is invoked with the parameter
MYFILE.DAT, these statements result in the symbol FILENAME
being given the value MYFILE.
Note that the F$LOCATE function in the above example assumes
that the file specification does not contain a node name or
a directory specification containing a subdirectory name. To
obtain the file name from a full file specification, use the
F$PARSE function.
3. $ IF F$EXTRACT(12,2,F$TIME()) .GES. "12" THEN GOTO AFTERNOON
$ MORNING:
$ WRITE SYS$OUTPUT "Good morning!"
$ EXIT
$ AFTERNOON:
$ WRITE SYS$OUTPUT "Good afternoon!"
$ EXIT
This example shows a procedure that displays a different
message, depending on whether the current time is morning or
afternoon. It first obtains the current time of day by using
the F$TIME function. The F$TIME function returns a character
string, which is the string argument for the F$EXTRACT
function. The F$TIME function is automatically evaluated when
it is used as an argument, so you do not need to use quotation
marks.
Next, the F$EXTRACT function extracts the hours from the date
and time string returned by F$TIME. The string returned by
F$TIME always contains the hours field beginning at an offset
of 12 characters from the start of the string.
The F$EXTRACT function extracts 2 characters from the string,
beginning at this offset, and compares the string value
extracted with the string value 12. If the comparison is true,
then the procedure writes "Good afternoon!". Otherwise, it
writes "Good morning!".
Note that you can also use the F$CVTIME function to extract
the hour field from a time specification. This method is easier
than the one shown in the above example.
F$FAO
Converts character and numeric input to ASCII character strings.
(FAO stands for formatted ASCII output.) By specifying formatting
instructions, you can use the F$FAO function to convert integer
values to character strings, to insert carriage returns and form
feeds, to insert text, and so on.
Format
F$FAO(control-string[,argument[,...]])
Additional information available:
Return Valuecontrol-stringargument[,...]Examples
Return Value
A character string containing formatted ASCII output. This output string is created from the fixed text and FAO directives in the control string.
control-string
Specifies the fixed text of the output string, consisting of
text and any number of FAO directives. The control string may
be any length. Specify the control string as a character string
expression.
The F$FAO function uses FAO directives to modify or insert ASCII
data into the fixed text in the control string.
Here is a summary of the FAO directives you can specify in a
control string.
Directive Argument Type Description
Character string insertion:
!AS String Inserts a character string as is.
Zero-filled numeric conversion:
!OB Integer Converts a byte to octal notation.
!OW Integer Converts a word to octal notation.
!OL Integer Converts a longword to octal notation.
!XB Integer Converts a byte to hexadecimal
notation.
!XW Integer Converts a word to hexadecimal
notation.
!XL Integer Converts a longword to hexadecimal
notation.
!ZB Integer Converts a byte to decimal notation.
!ZW Integer Converts a word to decimal notation.
!ZL Integer Converts a longword to decimal
notation.
Blank-filled numeric conversion:
!UB Integer Converts a byte to decimal notation
without adjusting for negative
numbers.
!UW Integer Converts a word to decimal notation
without adjusting for negative
numbers.
!UL Integer Converts a longword to decimal
notation
without adjusting for negative
numbers.
!SB Integer Converts a byte to decimal notation
with negative numbers converted
properly.
!SW Integer Converts a word to decimal notation
with negative numbers converted
properly.
!SL Integer Converts a longword to decimal
notation
with negative numbers converted
properly.
Special formatting:
!/ None Inserts a carriage return and a line
feed.
!_ None Inserts a tab.
!^ None Inserts a form feed.
!! None Inserts an exclamation point (!).
!%I Integer Converts a longword integer to a named
UIC in the format
[group-identifier,member-identifier].
!%S None Inserts an "s" if the most recently
converted number is not 1. (Not
recommended for use with multilingual
products.)
!%U Integer Converts a longword integer to a
numeric
UIC in the format [g,m], where g is
the group
number and m is the member number.
The directive inserts the brackets and
the comma.
!n<...!> None Left-justifies and blank-fills all
data
represented by the instructions . . .
in
fields n characters wide.
!n*c None Repeats the character represented
by c for n times.
!n%C String Inserts a character string when the
most recently evaluated argument has
the value n. (Recommended for use with
multilingual products.)
!%E String Inserts a character string when the
value of the most recently evaluated
argument does not match any preceding
!n%C directives. (Recommended for use
with multilingual products.)
!%F None Marks the end of a plurals statement.
!%T Integer equal Inserts the current time.
to 0
!%D Integer equal Inserts the current date/time.
to 0
Argument interpretation:
!- None Reuses the last argument.
!+ None Skips the next argument.
argument[,...]
Specifies from 1 to 15 arguments required by the FAO directives used in the control string. Specify the arguments as integer or character string expressions. FAO directives may require one or more arguments. The order of the arguments must correspond exactly with the order of the directives in the control string. In most cases, an error message is not displayed if you misplace an argument. If you specify an argument whose type (integer or string) does not match that of the corresponding directive, unpredictable results are returned. You can use the F$INTEGER and F$STRING lexical functions to convert arguments to the proper type. If there are not enough arguments listed, F$FAO continues reading past the end of an argument list. Therefore, always be sure to include enough arguments to satisfy the requirements of all the directives in a control string. If you specify an invalid parameter for any directive, you may see unexpected errors, which indicate that the command did not succeed. (These errors are passed through to you from the $FAO system service.)
Examples
1. $ COUNT = 57
$ REPORT = F$FAO("NUMBER OF FORMS = !SL",COUNT)
$ SHOW SYMBOL REPORT
$ REPORT = "NUMBER OF FORMS = 57"
In this command procedure, the FAO directive !SL is used in
a control string to convert the number equated to the symbol
COUNT to a character string. The converted string is inserted
into the control string.
Note that COUNT is assigned an integer value of 57. The F$FAO
function returns the ASCII string, "NUMBER OF FORMS = 57", and
assigns the string to the symbol REPORT.
2. $ A = "ERR"
$ B = "IS"
$ C = "HUM"
$ D = "AN"
$ PHRASE = F$FAO("TO !3(AS)",A,B,C+D)
$ SHOW SYMBOL PHRASE
$ PHRASE = "TO ERRISHUMAN"
In this command procedure, the !AS directive is used to insert
the values assigned to the symbols A, B, C, and D into the
control string.
Because the specified repeat count for the !AS directive is 3,
F$FAO looks for three arguments. The arguments in this example
include the symbol A ("ERR"), the symbol B ("IS"), and the
expression C+D ("HUMAN"). Note that the values of these string
arguments are concatenated to form the string "ERRISHUMAN".
3. $ A = "ERR"
$ B = "IS"
$ C = "HUMAN"
$ PHRASE = F$FAO("TO !#(#AS)",3,6,A,B,C)
$ SHOW SYMBOL PHRASE
$ PHRASE = "TO ERR IS HUMAN "
In this command procedure, the F$FAO function is used with
the !AS directive to format a character string. The first
number sign (#) represents the repeat count given by the
first argument, 3. The second number sign represents the field
size given by the second argument, 6. The next three arguments
(A,B,C) provide the strings that are placed into the control
string each time the !AS directive is repeated.
Each argument string is output to a field having a length of
6 characters. Because each string is less than 6 characters,
each field is left-justified and padded with blank spaces. The
resulting string is assigned to the symbol PHRASE.
4.
$ OFFSPRING = 1
$ REPORT = F$FAO -
_$ ("There !0UL!1%Cis!Eare!%F !-!UL !1%Cchild!%Echildren!%Fhere",'OFFSPRING')
$ SHOW SYMBOL REPORT
$ REPORT ="There is 1 child here"
In this command procedure, the !0UL directive evaluates the
argument OFFSPRING but does not insert the value in the output
string. The !n%C directive inserts the character string "is"
into the output string because its value and the value of the
argument OFFSPRING match. The directives !-!UL evaluate the
argument a second time so that the correct character string can
be inserted in the proper place in the output string. The !%F
directive marks the end of each plurals statement. The F$FAO
function returns the ASCII string "There is 1 child here" and
assigns the string to the symbol REPORT.
F$FILE_ATTRIBUTES
Returns attribute information for a specified file.
Format
F$FILE_ATTRIBUTES(filespec,item)
Additional information available:
Return ValuefilespecitemExamples
Return Value
Either an integer or a character string, depending on the item you request.
filespec
Specifies the name of the file about which you are requesting information. You must specify the file name as a character string expression. You can specify only one file name. Wildcard characters are not allowed.
item
Indicates which attribute of the file is to be returned. The item
argument must be specified as a character string expression, and
can be any one of the these VMS RMS field names.
Table - F$FILE_ATTRIBUTES Items
Return
Item Type Information Returned
AI String TRUE if after-image (AI) journaling is
enabled; returns TRUE or FALSE
ALQ Integer Allocation quantity
BDT String Backup date/time
BI String TRUE if before-image (BI) journaling is
enabled; returns TRUE or FALSE
BKS Integer Bucket size
BLS Integer Block size
CBT String TRUE if contiguous-best-try; returns TRUE
or FALSE
CDT String Creation date/time
CTG String TRUE if contiguous; returns TRUE or FALSE
DEQ Integer Default extension quantity
DID String Directory ID string
DVI String Device name string
EDT String Expiration date/time
EOF Integer Number of blocks used
ERASE String TRUE if a file's contents are erased
before a file is deleted; returns TRUE or
FALSE
FFB Integer First free byte
FID String File ID string
FSZ Integer Fixed control area size
GBC Integer Global buffer count
GRP Integer Owner group number
JOURNAL_FILE String TRUE if the file is a journal; returns
TRUE or FALSE
KNOWN String Known file; returns TRUE or FALSE to
indicate whether file is installed with
the Install Utility (INSTALL)
LOCKED String TRUE if a file is deaccessed-locked;
returns TRUE or FALSE
MBM Integer Owner member number
MRN Integer Maximum record number
MRS Integer Maximum record size
NOA Integer Number of areas
NOBACKUP String FALSE if the file is marked for backup;
TRUE if the file is marked NOBACKUP
NOK Integer Number of keys
ORG String File organization; returns SEQ, REL, IDX
PRO String File protection string
PVN Integer Prolog version number
RAT String Record attributes; returns CR, PRN, FTN,
""
RCK String TRUE if read check; returns TRUE, FALSE
RDT String Revision date/time
RFM String Record format string; returns the values
VAR, FIX, VFC, UDF, STM, STMLF, STMCR
RU String TRUE if recovery unit (RU) journaling is
enabled; returns TRUE or FALSE
RVN Integer Revision number
STORED_ String ASCII string that represents stored
SEMANTICS semantics
UIC String Owner user identification code (UIC)
string
WCK String TRUE if write check; returns TRUE, FALSE
Examples
1. $ FILE_ORG = F$FILE_ATTRIBUTES("QUEST.DAT","ORG")
$ SHOW SYMBOL FILE_ORG
FILE_ORG = "SEQ"
This example uses the F$FILE_ATTRIBUTES function to assign the
value of the file organization type to the symbol FILE_ORG. The
F$FILE_ATTRIBUTES function returns the character string SEQ to
show that QUEST.DAT is a sequential file.
The QUEST.DAT and ORG arguments for the F$FILE_ATTRIBUTES
function are string literals and must be enclosed in quotation
marks (" ") when used in expressions.
2. $ RFM = F$FILE_ATTRIBUTES("KANSAS::USE$:[CARS]SALES.CMD","RFM")
$ SHOW SYMBOL RFM
RFM = "VAR"
This example uses the F$FILE_ATTRIBUTES function to return
information about a file on a remote node. The function returns
the record format string VAR, indicating that records are
variable length.
F$GETDVI
Returns a specified item of information for a specified device.
Format
F$GETDVI(device-name,item)
Additional information available:
Return Valuedevice-nameitemExample
Return Value
Either an integer or a character string, depending on the item you request.
device-name
Specifies a physical device name or a logical name equated to a physical device name. Specify the device name as a character string expression. After the device-name argument is evaluated, the F$GETDVI function examines the first character of the name. If the first character is an underscore (_), the name is considered a physical device name. Otherwise, a single level of logical name translation is performed and the equivalence name, if any, is used.
item
Specifies the type of device information to be returned. The item must be specified as a character string expression. You may specify any one of the items listed below: ACPPID ACPTYPE ALL ALLDEVNAM ALLOCLASS ALT_HOST_AVAIL ALT_HOST_NAME ALT_HOST_TYPE AVL CCL CLUSTER CONCEALED CYLINDERS DEVBUFSIZ DEVCHAR DEVCHAR2 DEVCLASS DEVDEPEND DEVDEPEND2 DEVLOCKNAM DEVNAM DEVSTS DEVTYPE DFS_ACCESS DIR DMT DUA ELG ERRCNT EXISTS FOD FOR FREEBLOCKS FULLDEVNAM GEN HOST_AVAIL HOST_COUNT HOST_NAME HOST_TYPE IDV LOCKID LOGVOLNAM MAXBLOCK MAXFILES MBX MEDIA_ID MEDIA_NAME MEDIA_TYPE MNT MOUNTCNT NET NEXTDEVNAM ODV OPCNT OPR OWNUIC PID RCK RCT REC RECSIZ REFCNT REMOTE_DEVICE RND ROOTDEVNAM RTM SDI SECTORS SERIALNUM SERVED_DEVICE SET_HOST_TERMINAL SHDW_CATCHUP_COPYING SHDW_FAILED_MEMBER SHDW_MASTER SHDW_MASTER_NAME SHDW_MEMBER SHDW_MERGE_COPYING SHDW_NEXT_MBR_NAME SHR SPL SPLDEVNAM SQD STS SWL TRACKS TRANSCNT TRM TT_ACCPORNAM TT_ALTYPEAHD TT_ANSICRT TT_APP_KEYPAD TT_AUTOBAUD TT_AVO TT_BLOCK TT_BRDCSTMBX TT_CRFILL TT_DECCRT TT_DECCRT2 TT_DECCRT3 TT_DECCRT4 TT_DIALUP TT_DISCONNECT TT_DMA TT_DRCS TT_EDIT TT_EDITING TT_EIGHTBIT TT_ESCAPE TT_FALLBACK TT_HALFDUP TT_HANGUP TT_HOSTSYNC TT_INSERT TT_LFFILL TT_LOCALECHO TT_LOWER TT_MBXDSABL TT_MECHFORM TT_MECHTAB TT_MODEM TT_MODHANGUP TT_NOBRDCST TT_NOECHO TT_NOTYPEAHD TT_OPER TT_PAGE TT_PASTHRU TT_PHYDEVNAM TT_PRINTER TT_READSYNC TT_REGIS TT_REMOTE TT_SCOPE TT_SECURE TT_SETSPEED TT_SIXEL TT_SYSPWD TT_TTSYNC TT_WRAP UNIT VOLCOUNT VOLNAM VOLNUMBER VOLSETMEM VPRO WCK
Example
$ ERR = F$GETDVI("_DQA0","ERRCNT")
$ SHOW SYMBOL ERR
ERR = 0 Hex = 00000000 Octal = 000000
This example shows how to use the F$GETDVI function to return
an error count for the device DQA0. You must place quotation
marks (" ") around the device name DQA0 and the item ERRCNT
because they are string literals.
F$GETJPI
Returns accounting, status, and identification information for the
specified process.
Requires GROUP privilege to obtain information on other processes
in the same group. Requires WORLD privilege to obtain information
on any other processes in the system.
Format
F$GETJPI(pid,item)
Additional information available:
Return Value
Either an integer or a character string, depending on the item you request.
pid
Specifies the process identification (PID) number of the process
for which information is being reported. Specify the pid argument
as a character string expression. You can omit the leading zeros.
If you specify a null string (""), the current PID number is used.
You cannot use a wildcard to specify the pid argument in the
F$GETJPI function, as you can with the $GETJPI system service.
To get a list of process identification numbers, use the F$PID
function.
item
Indicates the type of process information to be returned. Specify the item argument as a character string expression. You can specify any one of the following items: ACCOUNT APTCNT ASTACT ASTCNT ASTEN ASTLM AUTHPRI AUTHPRIV BIOCNT BIOLM BUFIO BYTCNT BYTLM CLINAME CPULIM CPUTIM CREPRC_FLAGS CURPRIV DFPFC DFWSCNT DIOCNT DIOLM DIRIO EFCS EFCU EFWM ENQCNT ENQLM EXCVEC FAST_VP_SWITCH FILCNT FILLM FINALEXC FREP0VA FREP1VA FREPTECNT GPGCNT GRP IMAGECOUNT IMAGNAME IMAGPRIV JOBPRCCNT JOBTYPE LAST_LOGIN_I LAST_LOGIN_N LOGIN_FAILURES LOGIN_FLAGS LOGINTIM MASTER_PID MAXDETACH MAXJOBS MEM MODE MSGMASK OWNER PAGEFLTS PAGFILCNT PAGFILLOC PGFLQUOTA PHDFLAGS PID PPGCNT PRCCNT PRCLM PRCNAM PRI PRIB PROC_INDEX PROCESS_RIGHTS PROCPRIV RIGHTSLIST SHRFILLM SITESPEC SLOW_VP_SWITCH STATE STS SWPFILLOC SYSTEM_RIGHTS TABLENAME TERMINAL TMBU TQCNT TQLM UAF_FLAGS UIC USERNAME VIRTPEAK VOLUMES VP_CONSUMER VP_CPUTIM WSAUTH WSAUTHEXT WSEXTENT WSPEAK WSQUOTA WSSIZE
Example
$ NAME = F$GETJPI("3B0018","USERNAME")
$ SHOW SYMBOL NAME
NAME = "JANE"
This example shows how to use the F$GETJPI function to return
the user name for the process number 3B0018. The user name is
assigned to the symbol NAME.
F$GETQUI
Returns information about queues, batch and print jobs currently
in those queues, form definitions, and characteristic definitions
kept in the system job queue file.
Requires read access to the job or OPER (operator) privilege to
obtain job and file information.
Format
F$GETQUI(function,[item],[object-id],[flags])
Additional information available:
Return Valuefunctionitemobject-idflagsExamples
Return Value
Either an integer or a character string, depending on the item you
request. For items that return a Boolean value, the string is TRUE
or FALSE. If the $GETQUI system service returns an error code,
F$GETQUI returns a null string ("").
function
Specifies the action that the F$GETQUI lexical function is to
perform. F$GETQUI supports all functions that can be specified
with the $GETQUI system service. They are listed in the following
table:
Function Description
CANCEL_OPERATION Terminates any wildcard operation that
may have been initiated by a previous
call to F$GETQUI.
DISPLAY_CHARACTERISTIC Returns information about a specific
characteristic definition or the next
characteristic definition in a wildcard
operation.
DISPLAY_ENTRY Returns information about a specific
job entry or the next job entry that
matches the selection criteria in
a wildcard operation. The DISPLAY_
ENTRY function code is similar to the
DISPLAY_JOB function code in that both
return job information. DISPLAY_JOB,
however, requires that a call be made to
establish queue context; DISPLAY_ENTRY
does not require that queue context be
established.
DISPLAY_FILE Returns information about the next file
defined for the current job context.
Before you make a call to F$GETQUI
to request file information, you must
make a call to display queue and job
information (with the DISPLAY_QUEUE and
DISPLAY_JOB function codes) or to display
entry information (with the DISPLAY_ENTRY
function code).
DISPLAY_FORM Returns information about a specific form
definition or the next form definition in
a wildcard operation.
DISPLAY_JOB Returns information about the next job
defined for the current queue context.
Before you make a call to F$GETQUI to
request job information, you must make a
call to display queue information (with
the DISPLAY_QUEUE function code). The
DISPLAY_JOB function code is similar to
the DISPLAY_ENTRY function code in that
both return job information. DISPLAY_JOB,
however, requires that a call be made to
establish queue context; DISPLAY_ENTRY
does not require that queue context be
established.
DISPLAY_QUEUE Returns information about a specific
queue definition or the next queue
definition in a wildcard operation.
TRANSLATE_QUEUE Translates a logical name for a queue to
the equivalence name for the queue.
Some function arguments cannot be specified with the item-
code, the object-id, or the flags argument. The following table
lists each function argument and corresponding format line to
show whether the item-code, object-id and flags arguments are
required, optional, or not applicable for that specific function.
In the following format lines, brackets ([ ]) denote an optional
argument. An omitted argument means the argument is not applicable
for that function. Note that two commas (,,) must be used as
placeholders to denote an omitted (whether optional or not
applicable) argument.
Function Format Line
CANCEL_OPERATION F$GETQUI("CANCEL_OPERATION") or
F$GETQUI("")
DISPLAY_CHARACTERISTIC F$GETQUI("DISPLAY_
CHARACTERISTIC",[item],object-id,[flags])
DISPLAY_ENTRY F$GETQUI("DISPLAY_ENTRY",[item],[object-
id],[flags])
DISPLAY_FILE F$GETQUI("DISPLAY_FILE",[item],,[flags])
DISPLAY_FORM F$GETQUI("DISPLAY_FORM",[item],object-
id,[flags])
DISPLAY_JOB F$GETQUI("DISPLAY_JOB",[item],,[flags])
DISPLAY_QUEUE F$GETQUI("DISPLAY_QUEUE",[item],object-
id,[flags])
TRANSLATE_QUEUE F$GETQUI("TRANSLATE_QUEUE",[item],object-
id)
item
Corresponds to a $GETQUI system service output item code. The item
argument specifies the kind of information you want returned about
a particular queue, job, file, form, or characteristic.
These are the item codes:
ACCOUNT_NAME AFTER_TIME ASSIGNED_QUEUE_NAME
BASE_PRIORITY CHARACTERISTICS CHARACTERISTIC_NAME
CHARACTERISTIC_NUMBER CHECKPOINT_DATA
CLI COMPLETED_BLOCKS CONDITION_VECTOR
CPU_DEFAULT CPU_LIMIT DEFAULT_FORM_NAME
DEFAULT_FORM_STOCK DEVICE_NAME
ENTRY_NUMBER EXECUTING_JOB_COUNT
FILE_BURST FILE_CHECKPOINTED FILE_COPIES
FILE_COPIES_DONE FILE_DELETE FILE_DOUBLE_SPACE
FILE_EXECUTING FILE_FLAG FILE_FLAGS
FILE_IDENTIFICATION FILE_PAGE_HEADER
FILE_PAGINATE FILE_PASSALL FILE_SETUP_MODULES
FILE_SPECIFICATION FILE_STATUS
FILE_TRAILER FIRST_PAGE FORM_DESCRIPTION
FORM_FLAGS FORM_LENGTH FORM_MARGIN_BOTTOM
FORM_MARGIN_LEFT FORM_MARGIN_RIGHT FORM_MARGIN_TOP
FORM_NAME FORM_NUMBER FORM_SETUP_MODULES
FORM_SHEET_FEED FORM_STOCK FORM_TRUNCATE
FORM_WIDTH FORM_WRAP GENERIC_TARGET
HOLDING_JOB_COUNT INTERVENING_BLOCKS
INTERVENING_JOBS JOB_ABORTING JOB_COPIES
JOB_COPIES_DONE JOB_CPU_LIMIT JOB_EXECUTING
JOB_FILE_BURST JOB_FILE_BURST_ONE
JOB_FILE_FLAG JOB_FILE_FLAG_ONE JOB_FILE_PAGINATE
JOB_FILE_TRAILER JOB_FILE_TRAILER_ONE
JOB_FLAGS JOB_HOLDING JOB_INACCESSIBLE
JOB_LIMIT JOB_LOG_DELETE JOB_LOG_NULL
JOB_LOG_SPOOL JOB_LOWERCASE JOB_NAME
JOB_NOTIFY JOB_PENDING JOB_PID
JOB_REFUSED JOB_RESET_MODULES JOB_RESTART
JOB_RETAINED JOB_SIZE JOB_SIZE_MAXIMUM
JOB_SIZE_MINIMUM JOB_STARTING JOB_STATUS
JOB_SUSPENDED JOB_TIMED_RELEASE JOB_WSDEFAULT
JOB_WSEXTENT JOB_WSQUOTA LAST_PAGE
LIBRARY_SPECIFICATION LOG_QUEUE
LOG_SPECIFICATION NOTE OPERATOR_REQUEST
OWNER_UIC PAGE_SETUP_MODULES
PARAMETER_1 to PARAMETER_8 PENDING_JOB_BLOCK_COUNT
PENDING_JOB_COUNT PENDING_JOB_REASON
PEND_CHAR_MISMATCH PEND_JOB_SIZE_MAX
PEND_JOB_SIZE_MIN PEND_LOWERCASE_MISMATCH
PEND_NO_ACCESS PEND_QUEUE_BUSY PEND_QUEUE_STATE
PEND_STOCK_MISMATCH PRIORITY
PROCESSOR PROTECTION QUEUE_ACL_SPECIFIED
QUEUE_ALIGNING QUEUE_BATCH QUEUE_CLOSED
QUEUE_CPU_DEFAULT QUEUE_CPU_LIMIT QUEUE_DESCRIPTION
QUEUE_FILE_BURST QUEUE_FILE_BURST_ONE
QUEUE_FILE_FLAG QUEUE_FILE_FLAG_ONE
QUEUE_FILE_PAGINATE QUEUE_FILE_TRAILER
QUEUE_FILE_TRAILER_ONE QUEUE_FLAGS
QUEUE_GENERIC QUEUE_GENERIC_SELECTION
QUEUE_IDLE QUEUE_JOB_BURST QUEUE_JOB_FLAG
QUEUE_JOB_SIZE_SCHED QUEUE_JOB_TRAILER
QUEUE_LOWERCASE QUEUE_NAME QUEUE_PAUSED
QUEUE_PAUSING QUEUE_PRINTER QUEUE_RECORD_BLOCKING
QUEUE_REMOTE QUEUE_RESETTING QUEUE_RESUMING
QUEUE_RETAIN_ALL QUEUE_RETAIN_ERROR
QUEUE_SERVER QUEUE_STALLED QUEUE_STARTING
QUEUE_STATUS QUEUE_STOPPED QUEUE_STOPPING
QUEUE_SWAP QUEUE_TERMINAL QUEUE_UNAVAILABLE
QUEUE_WSDEFAULT QUEUE_WSEXTENT QUEUE_WSQUOTA
REQUEUE_QUEUE_NAME RESTART_QUEUE_NAME
RETAINED_JOB_COUNT SCSNODE_NAME
SUBMISSION_TIME TIMED_RELEASE_JOB_COUNT
UIC USERNAME WSDEFAULT
WSEXTENT WSQUOTA
object-id
Corresponds to the $GETQUI system service QUI$SEARCH_NAME and
QUI$_SEARCH_NUMBER input item codes. The object-id argument
specifies either the name or number of an object (for example,
a specific queue name or form number) about which F$GETQUI is to
return information. Wildcard characters (* and %) are allowed for
the following functions:
o DISPLAY_CHARACTERISTIC
o DISPLAY_ENTRY
o DISPLAY_FORM
o DISPLAY_QUEUE
By specifying a wildcard as the object-id argument on successive
calls, you can get status information about one or more jobs in
a specific queue or about files within jobs in a specific queue.
When a wildcard name is used, each call returns information for
the next object (queue, form, and so on) in the list. A null
string ("") is returned when the end of the list is reached. A
wildcard can represent only object names, not object numbers.
flags
Specifies a list of keywords, separated by commas, that
corresponds to the flags defined for the $GETQUI system service
QUI$_SEARCH_FLAGS input item code. (These flags are used to
define the scope of the object search specified in the call to
the $GETQUI system service.) Note that the following keywords can
be used only with certain function codes:
Keyword Valid Function Code Description
ALL_JOBS DISPLAY_JOB Requests that F$GETQUI
search all jobs included
in the established
queue context. If you
do not specify this
flag, F$GETQUI returns
information only about
jobs that have the same
user name as the caller.
BATCH DISPLAY_QUEUE Selects batch queues.
DISPLAY_ENTRY
EXECUTING_JOBS DISPLAY_ENTRY Selects executing jobs.
DISPLAY_JOB
FREEZE_CONTEXT DISPLAY_ When in wildcard mode,
CHARACTERISTIC prevents advance of
DISPLAY_ENTRY wildcard context to the
DISPLAY_FILE next object. If you do
DISPLAY_FORM not specify this flag,
DISPLAY_JOB the context is advanced
DISPLAY_QUEUE to the next object.
GENERIC DISPLAY_QUEUE Selects generic queues
for searching.
HOLDING_JOBS DISPLAY_ENTRY Selects jobs on
DISPLAY_JOB unconditional hold.
PENDING_JOBS DISPLAY_ENTRY Selects pending jobs.
DISPLAY_JOB
PRINTER DISPLAY_QUEUE Selects printer queues.
DISPLAY_ENTRY
RETAINED_JOBS DISPLAY_ENTRY Selects jobs being
DISPLAY_JOB retained.
SERVER DISPLAY_QUEUE Selects server queues.
DISPLAY_ENTRY
SYMBIONT DISPLAY_QUEUE Selects all output
DISPLAY_ENTRY queues. Equivalent to
specifying "PRINTER,
SERVER, TERMINAL".
TERMINAL DISPLAY_QUEUE Selects terminal queues.
DISPLAY_ENTRY
THIS_JOB DISPLAY_FILE Selects all job file
DISPLAY_JOB DISPLAY_ information about the
QUEUE calling batch job,
the command file being
executed, or the queue
associated with the
calling batch job.
TIMED_RELEASE_JOBS DISPLAY_ENTRY Selects jobs on hold
DISPLAY_JOB until a specified time.
WILDCARD DISPLAY_ Establishes and saves
CHARACTERISTIC a context. Because the
DISPLAY_ENTRY context is saved, the
DISPLAY_FORM next operation can be
DISPLAY_QUEUE performed based on that
context.
Examples
1. $ BLOCKS = F$GETQUI("DISPLAY_ENTRY"
"JOB_SIZE", 1347)
In this example, the F$GETQUI lexical function is used to
obtain the size in blocks of print job 1347. The value returned
reflects the total number of blocks occupied by the files
associated with the job.
2. $ IF F$GETQUI("DISPLAY_QUEUE", "QUEUE_STOPPED", "VAX1_BATCH") .EQS.
"TRUE" THEN GOTO 500
In this example, the F$GETQUI lexical function is used to
return a value of TRUE or FALSE depending on whether the queue
VAX1_BATCH is in a stopped state. If VAX1_BATCH is not in the
system, F$GETQUI returns a null string ("").
3.
$! This command procedure shows all queues and the jobs in them.
$ TEMP = F$GETQUI("")
$ QLOOP:
$ QNAME = F$GETQUI("DISPLAY_QUEUE","QUEUE_NAME","*")
$ IF QNAME .EQS. "" THEN EXIT
$ WRITE SYS$OUTPUT ""
$ WRITE SYS$OUTPUT "QUEUE: ", QNAME
$ JLOOP:
$ NOACCESS = F$GETQUI("DISPLAY_JOB","JOB_INACCESSIBLE",,"ALL_JOBS")
$ IF NOACCESS .EQS. "TRUE" THEN GOTO JLOOP
$ IF NOACCESS .EQS. "" THEN GOTO QLOOP
$ JNAME = F$GETQUI("DISPLAY_JOB","JOB_NAME",,"FREEZE_CONTEXT,ALL_JOBS")
$ WRITE SYS$OUTPUT " JOB: ", JNAME
$ GOTO JLOOP
This sample command procedure displays all the queues in the
system and all the jobs that the user has read access to in the
system. In the outer loop a wildcard display queue operation
is performed. No call is made to establish the right to obtain
information about the queue, because all users have implicit
read access to queue attributes. Because a wildcard queue name
is specified ("*"), wildcard queue context is maintained across
calls to F$GETQUI.
In the inner loop, to obtain information about all jobs, we
enter nested wildcard mode from wildcard display queue mode.
In this loop, a call is made to establish the right to obtain
information about these jobs because users do not have implicit
read access to jobs. The FREEZE_CONTEXT keyword is used in
the request for a job name to prevent the advance of the
wildcard context to the next object. After the job name has
been retrieved and displayed, the procedure loops back up for
the next job. The context is advanced because the procedure has
not used the FREEZE_CONTEXT keyword. The wildcard queue context
is dissolved when the list of matching queues is exhausted.
Finally, F$GETQUI returns a null string ("") to denote that no
more objects match the specified search criteria.
F$GETSYI
Returns status and identification information about the local
system (or about a node in the local VAXcluster, if your system is
part of a VAXcluster).
Format
F$GETSYI(item [,node-name] [,cluster-id])
Additional information available:
Return Valueitemnode-namecluster-idExamples
Return Value
Either an integer or a character string, depending on the item you request.
item
Indicates the type of information to be reported about the local
node (or about another node in your VAXcluster, if your system
is part of a VAXcluster). Specify the item as a character string
expression. Here are the items you can specify with the F$GETSYI
lexical function to get information about your local node. You
cannot specify the node-name argument with these items.
ACTIVECPU_CNT AVAILCPU_CNT ARCHFLAG BOOTTIME
CHARACTER_EMULATED CONTIG_GBLPAGES CPU DECIMAL_EMULATED
D_FLOAT_EMULATED F_FLOAT_EMULATED FREE_GBLPAGES FREE_GBLSECTS
G_FLOAT_EMULATED PAGEFILE_FREE PAGEFILE_PAGE SID
SWAPFILE_FREE SWAPFILE_PAGE VERSION
Here are the items you can specify to get information about either
your local node, or another node in your VAXcluster. If you do
not specify the node argument, the information is returned for the
local node.
CLUSTER_FSYSID CLUSTER_FTIME CLUSTER_MEMBER CLUSTER_NODES
CLUSTER_QUORUM CLUSTER_VOTES HW_MODEL HW_NAME
NODENAME NODE_AREA NODE_CSID NODE_HWTYPE
NODE_HWVERS NODE_NUMBER NODE_QUORUM NODE_SWINCARN
NODE_SWTYPE NODE_SWVERS NODE_SYSTEMID NODE_VOTES
SCS_EXISTS SYSTEM_RIGHTS VECTOR_EMULATOR VP_MASK
VP_NUMBER
node-name
Specifies the node in your VAXcluster for which information is to be returned. Specify the node as a character string expression. You cannot use wildcards to specify the node-name argument. (This argument can be specified only if your system is part of a VAXcluster.)
cluster-id
Specifies the cluster node identification number for which the information is to be returned. (This argument can be specified only if your system is part of a VAXcluster.) To get information for all the nodes in a cluster, use the F$CSID lexical function to obtain each cluster system identification number and use the cluster-id argument of F$GETSYI to gather information about each node.
Examples
1. $ SYSID = F$GETSYI("SID")
$ SHOW SYMBOL SYSID
SYSID = 19923201 Hex = 01300101 Octal = 000401
This example shows how to use the F$GETSYI function to return
the information in the system identification register. Use
quotation marks (" ") around the argument SID because it is a
string literal. The value returned by F$GETSYI is assigned to
the symbol SYSID. Because a node is not specified, information
about your current node is returned.
2. $ MEM = F$GETSYI("CLUSTER_MEMBER", "LONDON")
$ SHOW SYMBOL MEM
MEM = "TRUE"
This example uses the F$GETSYI function to determine whether
the node LONDON is a member of the local VAXcluster. The return
value TRUE indicates that the remote node LONDON is a member of
the VAXcluster.
3. $ LIM = F$GETSYI("BJOBLIM")
$ SHOW SYMBOL LIM
LIM = 16 Hex = 00000010 Octal = 00000000020
This example uses the SYSGEN parameter BJOBLIM as an argument
for the F$GETSYI function. This argument returns the batch job
limit for the current system.
F$IDENTIFIER
Converts an alphanumeric identifier to its integer equivalent, or
converts an integer identifier to its alphanumeric equivalent. An
identifier is a name or number that identifies a category of users
of a data resource. The system uses identifiers to determine a
user's access to a resource.
Format
F$IDENTIFIER(identifier,conversion-type)
Additional information available:
Return Valueidentifierconversion-typeExamples
Return Value
An integer value if you are converting an identifier from a name
to an integer. The F$IDENTIFIER function returns a string if you
are converting an identifier from an integer to a name. If you
specify an identifier that is not valid, the F$IDENTIFIER function
returns a null string ("") (if you are converting from number to
name) or a zero (if you are converting from name to number).
identifier
Specifies the identifier to be converted. Specify the identifier as an integer expression if you are converting an integer to a name. Specify the identifier as a character string expression if you are converting a name to an integer.
conversion-type
Indicates the type of conversion to be performed. If the identifier argument is alphanumeric, specify the conversion-type argument as a character string containing "NAME_TO_NUMBER". If the identifier argument is numeric, specify the conversion-type argument as a character string containing "NUMBER_TO_NAME".
Examples
1. $ UIC_INT= F$IDENTIFIER("SLOANE","NAME_TO_NUMBER")
$ SHOW SYMBOL UIC_INT
UIC_INT = 15728665 Hex = 00F00019 Octal = 00074000031
$ UIC = F$FAO("!%U",UIC_INT)
$ SHOW SYMBOL UIC
UIC = [360,031]
This example uses the F$IDENTIFIER to convert the member
identifier from the UIC [MANAGERS,SLOANE] to an integer. The
F$IDENTIFIER function shows that the member identifier SLOANE
is equivalent to the integer 15728665. Note that you must
specify the identifier SLOANE using uppercase letters.
To convert this octal number to a standard numeric user
identification code (UIC), use the F$FAO function with the
!%U directive. (This directive converts a longword to a UIC in
named format.) In this example, the member identifier SLOANE is
equivalent to the numeric UIC [360,031].
2. $ UIC_INT = (%O31 + (%X10000 * %O360))
$ UIC_NAME = F$IDENTIFIER(UIC_INT,"NUMBER_TO_NAME")
$ SHOW SYMBOL UIC_NAME
UIC_NAME = "ODONNELL"
This example obtains the alphanumeric identifier associated
with the numeric UIC [360,031]. First, you must obtain the
longword integer that corresponds to the UIC [360,031]. To
do this, place the member number into the low order word.
Place the group number into the high order word. Next, use the
F$IDENTIFIER function to return the named identifier associated
with the integer.
F$INTEGER
Returns the integer equivalent of the result of the specified
expression.
Format
F$INTEGER(expression)
Additional information available:
Return Value
An integer value that is equivalent to the specified expression.
expression
Specifies the expression to be evaluated. Specify either an integer or a character string expression. If you specify an integer expression, the F$INTEGER function evaluates the expression and returns the result. If you specify a string expression, the F$INTEGER function evaluates the expression, converts the resulting string to an integer, and returns the result. After evaluating a string expression, the F$INTEGER function converts the result to an integer in the following way. If the resulting string contains characters that form a valid integer, the F$INTEGER function returns the integer value. If the string contains characters that do not form a valid integer, the F$INTEGER function returns the integer 1 if the string begins with T, t, Y, or y. The function returns the integer 0 if the string begins with any other character.
Example
$ A = "23"
$ B = F$INTEGER("-9" + A)
$ SHOW SYMBOL B
B = -923 Hex=FFFFFC65 Octal=176145
This example shows how to use the F$INTEGER function to equate
a symbol to the integer value returned by the function. In the
example, the F$INTEGER function returns the integer equivalent
of the string expression ("-9" + A). First, the F$INTEGER
function evaluates the string expression by concatenating
the string literal "-9" with the string literal "23". Note
that the value of the symbol A is substituted automatically
in a string expression. Also note that the plus sign (+) is a
string concatenation operator since both arguments are string
literals.
After the string expression is evaluated, the F$INTEGER
function converts the resulting character string ("-923") to
an integer, and returns the value -923. This integer value is
assigned to the symbol B.
F$LENGTH
Returns the length of the specified character string.
Format
F$LENGTH(string)
Additional information available:
Return Value
An integer value for the length of the string.
string
Specifies the character string whose length is being determined. Specify the string argument as a character string expression.
Example
$ MESSAGE = F$MESSAGE(%X1C)
$ SHOW SYMBOL MESSAGE
MESSAGE = "%SYSTEM-F-EXQUOTA, exceeded quota"
$ STRING_LENGTH = F$LENGTH(MESSAGE)
$ SHOW SYMBOL STRING_LENGTH
STRING_LENGTH = 33 Hex = 00000021 Octal = 000041
The first assignment statement uses the F$MESSAGE function
to return the message that corresponds to the hexadecimal
value 1C. The message is returned as a character string and
is assigned to the symbol MESSAGE.
The F$LENGTH function is then used to return the length of
the character string assigned to the symbol MESSAGE. You
do not need to use quotation marks (" ") when you use the
symbol MESSAGE as an argument for the F$LENGTH function.
(Quotation marks are not used around symbols in character
string expressions.)
The F$LENGTH function returns the length of the character
string and assigns it to the symbol STRING_LENGTH. At the end
of the example, the symbol STRING_LENGTH has a value equal
to the number of characters in the value of the symbol named
MESSAGE, that is, 33.
F$LOCATE
Locates a specified portion of a character string and returns as
an integer the offset of the first character. If the substring
is not found, F$LOCATE returns the length (the offset of the
last character in the character string plus one) of the searched
string.
Format
F$LOCATE(substring,string)
Additional information available:
Return ValuesubstringstringExamples
Return Value
An integer value representing the offset of the substring argument. An offset is the position of a character or a substring relative to the beginning of the string. The first character in a string is always offset position 0 from the beginning of the string (which always begins at the leftmost character). If the substring is not found, the F$LOCATE function returns an offset of the last character in the character string plus 1. (This equals the length of the string.)
substring
Specifies the character string that you want to locate within the string specified in the string argument.
string
Specifies the character string to be edited by F$LOCATE.
Examples
1. $ FILE_SPEC = "MYFILE.DAT;1"
$ NAME_LENGTH = F$LOCATE(".",FILE_SPEC)
The F$LOCATE function in this example returns the position of
the period (.) in the string with respect to the beginning of
the string. The period is in offset position 6, so the value
6 is assigned to the symbol NAME_LENGTH. Note that NAME_LENGTH
also equals the length of the file name portion of the file
specification MYFILE.DAT, that is, 6.
The substring argument, the period, is specified as a string
literal and is therefore enclosed in quotation marks (" ").
The string argument FILE_SPEC is a symbol, so it should not be
placed within quotation marks. It is automatically replaced by
its current value during the processing of the function.
2. $ INQUIRE TIME "Enter time"
$ IF F$LOCATE(":",TIME) .EQ. F$LENGTH(TIME) THEN -
GOTO NO_COLON
This section of a command procedure compares the results of the
F$LOCATE and F$LENGTH functions to see if they are equal. This
technique is commonly used to determine whether a character or
substring is contained in a string.
In the example, the INQUIRE command prompts for a time value
and assigns the user-supplied time to the symbol TIME. The IF
command checks for the presence of a colon (:) in the string
entered in response to the prompt. If the value returned by
the F$LOCATE function equals the value returned by the F$LENGTH
function, the colon is not present. You use the .EQ. operator
(rather than .EQS.) because the F$LOCATE and F$LENGTH functions
return integer values.
Note that quotation marks are used around the substring
argument, the colon, because it is a string literal. However,
the symbol TIME does not require quotation marks because it is
automatically evaluated as a string expression.
F$MESSAGE
Returns as a character string the facility, severity,
identification, and text associated with the specified system
status code.
Format
F$MESSAGE(status-code)
Additional information available:
Return Valuestatus-codeExample
Return Value
A character string containing the system message that corresponds to the argument you specify. Note that, although each message in the system message file has a numeric value or range of values associated with it, there are many possible numeric values that do not have corresponding messages. If you specify an argument that has no corresponding message, the F$MESSAGE function returns a string containing the NOMSG error message. For more information on system error messages, see the VMS System Messages and Recovery Procedures Reference Volume.
status-code
Specifies the status code for which you are requesting error message text. You must specify the status code as an integer expression.
Example
$ ERROR_TEXT = F$MESSAGE(%X1C)
$ SHOW SYMBOL ERROR_TEXT
ERROR_TEXT = "%SYSTEM-F-EXQUOTA, exceeded quota"
This example shows how to use the F$MESSAGE function to
determine the message associated with the status code %X1C.
The F$MESSAGE function returns the message string, which is
assigned to the symbol ERROR_TEXT.
F$MODE
Returns a character string showing the mode in which a process
is executing. The F$MODE function has no arguments, but must be
followed by parentheses.
Format
F$MODE()
Additional information available:
Return ValueDescriptionExample
Return Value
The character string INTERACTIVE for interactive processes. If the process is noninteractive, the character string BATCH, NETWORK or OTHER is returned. Note that the return string always contains uppercase letters.
Description
The lexical function F$MODE returns a character string showing the mode in which a process is executing. The F$MODE function has no arguments, but must be followed by parentheses. The F$MODE function is useful in command procedures that must operate differently when executed interactively and noninteractively. You should include either the F$MODE function or the F$ENVIRONMENT function in your login command file to execute different commands for interactive terminal sessions and noninteractive sessions. If you do not include the F$MODE function to test whether your login command file is being executed from an interactive process, and the login command file is executed from a noninteractive process (such as a batch job), the process may terminate if the login command file contains commands that are appropriate only for interactive processing. A command procedure can use the F$MODE function to test whether the procedure is being executed during an interactive terminal session. It can direct the flow of execution according to the results of this test.
Example
$ IF F$MODE() .NES. "INTERACTIVE" THEN GOTO NON_INT_DEF
$ INTDEF: ! Commands for interactive terminal sessions
.
.
.
$ EXIT
$ NON_INT_DEF: !Commands for noninteractive processes
.
.
.
This example shows the beginning of a login.com file that has
two sets of initialization commands: one for interactive mode
and one for noninteractive mode (including batch and network
jobs). The IF command compares the character string returned
by F$MODE with the character string INTERACTIVE; if they are
not equal, control branches to the label NON_INT_DEF. If the
character strings are equal, the statements following the
label INTDEF are executed and the procedure exits before the
statements at NON_INT_DEF.
F$PARSE
Parses a file specification and returns either the expanded file
specification or the particular file specification field that you
request.
Format
F$PARSE(filespec [,default-spec] [,related-spec] [,field]
[,parse-type])
Additional information available:
Return Valuefilespecdefault-specrelated-specfieldparse-typeExamples
Return Value
A character string containing the expanded file specification
or the field you specify. If you do not provide a complete file
specification for the filespec argument, the F$PARSE function
supplies defaults in the return string.
If an error is detected during the parse, the F$PARSE function
returns a null string (""), except when you specify a field name
or the SYNTAX_ONLY parse type.
filespec
Specifies a character string containing the file specification to be parsed. The file specification can contain wildcard characters (* and %). If you use a wildcard character, the file specification returned by the F$PARSE function contains the wildcard.
default-spec
Specifies a character string containing the default file specification. The fields in the default file specification are substituted in the output string if a particular field in the filespec argument is missing. You can make further substitutions in the filespec argument by using the related-spec argument.
related-spec
Specifies a character string containing the related file specification. The fields in the related file specification are substituted in the output string if a particular field is missing from both the filespec and default-spec arguments.
field
Specifies a character string containing the name of a field in a file specification. Specifying the field argument causes the F$PARSE function to return a specific portion of a file specification. Specify one of the following field names (do not abbreviate): NODE Node name DEVICE Device name DIRECTORY Directory name NAME File name TYPE File type VERSION File version number
parse-type
Specifies the type of parsing to be performed. By default,
the F$PARSE function verifies that the directory in the file
specification exists on the device in the file specification.
However, the existence of the directory is not verified if you
provide a field argument. Note that the device and directory can
be explicitly given in one of the arguments, or can be provided by
default.
Also, by default the F$PARSE function translates logical names if
they are provided in any of the arguments. The F$PARSE function
stops iterative translation when it encounters a logical name with
the CONCEALED attribute.
You can change how the F$PARSE function parses a file
specification by using one of the following keywords:
NO_CONCEAL Ignores the "conceal" attribute in the translation
of a logical name as part of the file specification;
that is, logical name translation does not end when
a concealed logical name is encountered.
SYNTAX_ONLY The syntax of the file specification is checked
without verifying that the specified directory
exists on the specified device.
Examples
1. $ SET DEF DISK2:[FIRST]
$ SPEC = F$PARSE("JAMES.MAR","[ROOT]",,,"SYNTAX_ONLY")
$ SHOW SYMBOL SPEC
SPEC = "DISK2:[ROOT]JAMES.MAR;"
In this example, the F$PARSE function returns the expanded
file specification for the file JAMES.MAR. The example uses
the SYNTAX_ONLY keyword to request that F$PARSE check the
syntax, but should not verify that the [ROOT] directory exists
on DISK2.
The default device and directory are DISK2:[FIRST]. Because the
directory name [ROOT] is specified as the default-spec argument
in the assignment statement, it is used as the directory name
in the output string. Note that the default device returned
in the output string is DISK2, and the default version number
for the file is null. You must place quotation marks (" ")
around the arguments JAMES.MAR and ROOT because they are string
literals.
If you had not specified syntax-only parsing, and if [ROOT] were
not on DISK2, a null string would have been returned.
2. $ SET DEFAULT DB1:[VARGO]
$ SPEC = F$PARSE("INFO.COM",,,"DIRECTORY")
$ SHOW SYMBOL SPEC
SPEC = "[VARGO]"
In this example the F$PARSE function returns the directory
name of the file INFO.COM. Note that because the default-spec
and related-spec arguments are omitted from the argument list,
commas (,) must be inserted in their place.
3. $ SPEC= F$PARSE("DENVER::DB1:[PROD]RUN.DAT",,,"TYPE")
$ SHOW SYMBOL SPEC
SPEC = ".DAT"
In this example, the F$PARSE function is used to parse a file
specification containing a node name. The F$PARSE function
returns the file type DAT for the file RUN.DAT at the remote
node DENVER.
F$PID
Returns a process identification (PID) number and updates the
context symbol to point to the current position in the system's
process list.
Format
F$PID(context-symbol)
Additional information available:
Return Valuecontext-symbolExample
Return Value
A character string containing the process identification (PID) number of a process in the system's list of processes.
context-symbol
Specifies a symbol that DCL uses to store a pointer into the
system's list of processes. The F$PID function uses this pointer
to return a PID.
Specify the context symbol by using a symbol. The first time you
use the F$PID function in a command procedure, you should use
a symbol that is either undefined or equated to the null string
(""), or a context symbol that has been created by the F$CONTEXT
function.
If the context symbol is undefined or equated to a null string,
the F$PID function returns the first PID in the system's process
list that it has the privilege to access. That is, if you have
GROUP privilege and if the context symbol is null or undefined,
the F$PID function returns the PID of the first process in your
group. If you have WORLD privilege, the F$PID function returns the
PID of the first process in the list. If you have neither GROUP
nor WORLD privileges, the F$PID returns the first process that you
own. Subsequent calls to F$PID return the rest of the processes on
the system you are accessing.
If the context symbol has been created by the F$CONTEXT function,
the F$PID function returns the first process name in the system's
process list that fits the criteria specified in the F$CONTEXT
calls. Subsequent calls to F$PID return only the PIDs of those
processses that meet the selection criteria set up by the
F$CONTEXT function and that are accessible to your current
privileges.
Example
$ CONTEXT = ""
$ START:
$ PID = F$PID(CONTEXT)
$ IF PID .EQS. "" THEN EXIT
$ SHOW SYMBOL PID
$ GOTO START
This command procedure uses the F$PID function to display a
list of PIDs. The assignment statement declares the symbol
CONTEXT, which is used as the context-symbol argument for the
F$PID function. Because CONTEXT is equated to a null string,
the F$PID function returns the first PID in the process list
that it has the privilege to access.
The PIDs displayed by this command procedure depend on the
privilege of your process. When run with GROUP privilege, the
PIDs of users in your group are displayed. When run with WORLD
privilege, the PIDs of all users on the system are displayed.
Without GROUP or WORLD privilege, only those processes that you
own are displayed.
F$PRIVILEGE
Returns a string value of either TRUE or FALSE, depending on
whether your current process privileges match those specified
in the argument. You can specify either the positive or negative
version of a privilege.
Format
F$PRIVILEGE(priv-states)
Additional information available:
Return Valuepriv-statesExample
Return Value
A character string containing the value TRUE or FALSE. The F$PRIVILEGE function returns the string FALSE if any one of the privileges in the priv-states argument list is false.
priv-states
Specifies a character string containing a privilege or a list of privileges separated by commas (,). For a list of process privileges, see the VMS DCL Concepts Manual. Specify any one of the process privileges except [NO]ALL.
Example
$ PROCPRIV = F$PRIVILEGE("OPER,GROUP,TMPMBX,NONETMBX")
$ SHOW SYMBOL PROCPRIV
PROCPRIV = "FALSE"
The F$PRIVILEGE function is used to test whether the process
has OPER, USER, TMPMBX, and NETMBX privileges.
The process in this example has OPER (operator), GROUP, TMPMBX
(temporary mailbox), and NETMBX (network mailbox) privileges.
Therefore, a value of FALSE is returned because the process has
NETMBX privilege, but NONETMBX was specified in the priv-states
list. Although the Boolean result for the other three keywords
is true, the entire expression is declared false because the
result for NONETMBX was false.
F$PROCESS
Obtains the current process name string. The F$PROCESS function
has no arguments, but must be followed by parentheses.
Format
F$PROCESS()
Additional information available:
Return Value
A character string containing the current process name.
Example
$ NAME = F$PROCESS()
$ SHOW SYMBOL NAME
NAME = "MARTIN"
In this example, the F$PROCESS function returns the current
process name and assigns it to the symbol NAME.
F$SEARCH
Searches a directory file and returns the full file specification
for a file you specify.
Format
F$SEARCH(filespec[,stream-id])
Additional information available:
Return Valuefilespecstream-idExamples
Return Value
A character string containing the expanded file specification for
the filespec argument. If the F$SEARCH function does not find the
file in the directory, the function returns a null string ("").
filespec
Specifies a character string containing the file specification to be searched for. If the device or directory names are omitted, the defaults from your current default disk and directory are used. The F$SEARCH function does not supply defaults for a file name or type. If the version is omitted, the specification for the file with the highest version number is returned. If the filespec argument contains wildcards, each time F$SEARCH is called, the next file specification that agrees with the filespec argument is returned. A null string is returned after the last file specification that agrees with the filespec argument.
stream-id
Specifies a positive integer representing the search stream identification number. The search stream identification number is used to maintain separate search contexts when you use the F$SEARCH function more than once and when you supply different filespec arguments. If you use the F$SEARCH function more than once in a command procedure and if you also use different filespec arguments, specify stream- id arguments to identify each search separately. If you omit the stream-id argument, the F$SEARCH function assumes an implicit single search stream. That is, the F$SEARCH function starts searching at the beginning of the directory file each time you specify a different filespec argument.
Examples
1. $ START:
$ FILE = F$SEARCH("SYS$SYSTEM:*.EXE")
$ IF FILE .EQS. "" THEN EXIT
$ SHOW SYMBOL FILE
$ GOTO START
This command procedure displays the file specifications of the
latest version of all EXE files in the SYS$SYSTEM directory.
(Only the latest version is returned because a wildcard is
not used as the version number.) The filespec argument
SYS$SYSTEM:*.EXE is enclosed within quotation marks (" ")
because it is a character string expression.
Because no stream-id argument is specified, the F$SEARCH
function uses a single search stream. Each subsequent F$SEARCH
call uses the same filespec argument to return the next file
specification of an EXE file from SYS$SYSTEM:. After the latest
version of each EXE file has been displayed, the F$SEARCH
function returns a null string ("") and the procedure exits.
2. $ START:
$ COM = F$SEARCH ("*.COM;*",1)
$ DAT = F$SEARCH ("*.DAT;*",2)
$ SHOW SYMBOL COM
$ SHOW SYMBOL DAT
$ IF (COM.EQS. "") .AND. (DAT.EQS. "") THEN EXIT
$ GOTO START
This command procedure searches the default disk and directory
for both COM and DAT files. Note that the stream-id argument is
specified for each F$SEARCH call so that the context for each
search is maintained.
The first F$SEARCH call starts searching from the top of the
directory file for a file with a type of COM. When it finds a
COM file, a pointer is set to maintain the search context. When
the F$SEARCH function is used the second time, it again starts
searching from the top of the directory file for a file with a
type of DAT. When the procedure loops back to the label START,
the stream-id argument allows F$SEARCH to start searching in
the correct place in the directory file. After all versions of
COM and DAT files are returned, the procedure exits.
3. $ FILESPEC = F$SEARCH("TRNTO""SMITH SALLY""::DBA1:[PROD]*.DAT")
$ SHOW SYMBOL FILESPEC
FILESPEC = "TRNTO"smith password"::DBA1:[PROD]CARS.DAT"
This example uses the F$SEARCH function to return a file
specification for a file at a remote node. The access control
string is enclosed in quotation marks because it is part of
a character string expression when it is an argument for the
F$SEARCH function. To include quotation marks in a character
string expression, you must use two sets of quotation marks.
Note that, when the F$SEARCH function returns a node name
containing an access control string, it substitutes the word
"password" for the actual user password.
F$SETPRV
Enables or disables specified user privileges. The F$SETPRV
function returns a list of keywords indicating user privileges;
this list shows the status of the specified privileges before
F$SETPRV was executed.
Your process must be authorized to set the specified privilege.
For detailed information on privilege restrictions, see the
description of the $SETPRV system service in the VMS System
Services Reference Manual.
Format
F$SETPRV(priv-states)
Additional information available:
Return Valuepriv-statesExamples
Return Value
A character string containing keywords for the current process privileges before they were changed by the F$SETPRV function.
priv-states
Specifies a character string defining a privilege, or a list of privileges separated by commas (,). For a list of process privileges, see the VMS DCL Concepts Manual.
Examples
1. $ OLDPRIV = F$SETPRV("OPER,NOTMPMBX")
$ SHOW SYMBOL OLDPRIV
OLDPRIV = "NOOPER,TMPMBX"
In this example, the process is authorized to change the OPER
(operator) and TMPMBX (temporary mailbox) privileges. The
F$SETPRV function enables the OPER privilege and disables the
TMPMBX privilege. In addition, the F$SETPRV function returns
the keywords NOOPER and TMPMBX, showing the state of these
privileges before they were changed.
You must place quotation marks (" ") around the list of
privilege keywords because it is a string literal.
2. $ SHOW PROCESS/PRIVILEGE
19-APR-1990 15:55:09.60 RTA1: User: JACKSON
Process privileges:
Process rights identifiers:
INTERACTIVE
LOCAL
$ NEWPRIVS = F$SETPRV("ALL, NOOPER")
$ SHOW SYMBOL NEWPRIVS
NEWPRIVS = "NOCMKRNL,NOCMEXEC,NOSYSNAM,NOGRPNAM,NOALLSPOOL,NODETACH,
NODIAGNOSE,NOLOG_IO,NOGROUP,NOACNT,NOPRMCEB,NOPRMMBX,NOPSWAPM,
NOALTPRI,NOSETPRV,NOTMPMBX,NOWORLD,NOMOUNT,NOOPER,NOEXQUOTA,
NONETMBX,NOVOLPRO,NOPHY_IO,NOBUGCHK,NOPRMGBL,NOSYSGBL,NOPFNMAP,
NOSHMEM,NOSYSPRV,NOBYPASS,NOSYSLCK,NOSHARE,NOUPGRADE,NODOWNGRADE,
NOGRPPRV,NOREADALL,NOSECURITY,OPER"
$ SHOW PROCESS/PRIVILEGE
19-APR-1990 15:59:19.30 RTA1: User: JACKSON
Process privileges:
CMKRNL may change mode to kernel
CMEXEC may change mode to exec
SYSNAM may insert in system logical name table
GRPNAM may insert in group logical name table
ALLSPOOL may allocate spooled device
DETACH may create detached processes
DIAGNOSE may diagnose devices
LOG_IO may do logical i/o
GROUP may affect other processes in same group
ACNT may suppress accounting message
PRMCEB may create permanent common event clusters
PRMMBX may create permanent mailbox
PSWAPM may change process swap mode
ALTPRI may set any priority value
SETPRV may set any privilege bit
TMPMBX may create temporary mailbox
WORLD may affect other processes in the world
MOUNT may execute mount acp function
EXQUOTA may exceed quota
NETMBX may create network device
VOLPRO may override volume protection
PHY_IO may do physical i/o
BUGCHK may make bug check log entries
PRMGBL may create permanent global sections
SYSGBL may create system wide global sections
PFNMAP may map to specific physical pages
SHMEM may create/delete objects in shared memory
SYSPRV may access objects via system protection
BYPASS bypasses UIC checking
SYSLCK may lock system wide resources
SHARE may assign channels to non-shared device
GRPPRV group access via system protection
READALL may read anything as the owner
SECURITY may perform security functions
Process rights identifiers:
INTERACTIVE
LOCAL
$ NEWPRIVS = F$SETPRV(NEWPRIVS)
$ SHOW PROCESS/PRIVILEGE
19-APR-1990 16:05:07.23 RTA1: User: JACKSON
Process privileges:
OPER operator privilege
Process rights identifiers:
INTERACTIVE
LOCAL
In this example, the DCL command SHOW PROCESS/PRIVILEGE is
used to determine the current process privileges. Note that the
process has no privileges enabled.
The F$SETPRV function is then used to process the ALL keyword
and enable all privileges recording the previous state of each
privilege in the symbol NEWPRIVS. Next, F$SETPRV processes
the NOOPER keyword and disables the OPER (operator) privilege,
recording the previous state of OPER in NEWPRIVS. Note that the
OPER privilege appears in the returned string twice: first as
NOOPER and then as OPER.
Typing the command SHOW PROCESS/PRIVILEGE now shows that the
current process has all privileges enabled except OPER.
If the returned string is used as the parameter to F$SETPRV,
the process has the OPER privilege enabled. This occurs because
the OPER command was present twice in the symbol NEWPRIVS.
As a result, F$SETPRV looked at the first keyword NOOPER and
disabled the privilege. Finally, after processing several other
keywords in the NEWPRIVS string, the OPER keyword is presented
allowing F$SETPRV to enable the OPER privilege.
If you are using the ALL or NOALL keywords to save your current
privilege environment, Digital recommends that you perform
the following procedure to modify the process for a command
procedure:
$ CURRENT_PRIVS = F$SETPRV("ALL")
$ TEMP = F$SETPRV("NOOPER")
If you use this procedure, you can then specify the following
command statement at the end of your command procedure so that
the original privilege environment is restored:
$ TEMP = F$SETPRV(CURRENT_PRIVS)
3. $ SAVPRIV = F$SETPRV("NOGROUP")
$ SHOW SYMBOL SAVPRIV
SAVPRIV = "GROUP"
$ TEST = F$PRIVILEGE("GROUP")
$ SHOW SYMBOL TEST
TEST = "TRUE"
In this example, the process is not authorized to change the
GROUP privilege. However, the F$SETPRV function still returns
the current setting for the GROUP privilege.
The F$PRIVILEGE function is used to see whether the process has
GROUP privilege. The return string, TRUE, indicates that the
process has GROUP privilege, even though the F$SETPRV function
attempted to disable the privilege.
F$STRING
Returns the string that is equivalent to the specified expression.
Format
F$STRING(expression)
Additional information available:
Return Value
A character string equivalent to the specified expression.
expression
The integer or string expression to be evaluated. If you specify an integer expression, the F$STRING function evaluates the expression, converts the resulting integer to a string, and returns the result. If you specify a string expression, the F$STRING function evaluates the expression and returns the result. When converting an integer to a string, the F$STRING function uses decimal representation and omits leading zeroes. When converting a negative integer, the F$STRING function places a minus sign at the beginning string representation of the integer.
Example
$ A = 5
$ B = F$STRING(-2 + A)
$ SHOW SYMBOL B
B = "3"
The F$STRING function in this example converts the result of
the integer expression (-2 + A) to the numeric string, "3".
First, the F$STRING function evaluates the expression (-2
+ A). Note that 5, the value of symbol A, is automatically
substituted when the integer expression is evaluated.
After the integer expression is evaluated, the F$STRING
function converts the resulting integer, 3, to the string "3".
This string is assigned to the symbol B.
F$TIME
Returns the current date and time in absolute time format.
The F$TIME function has no arguments, but must be followed by
parentheses.
Format
F$TIME()
Additional information available:
Return Value
A character string containing the current date and time. The returned string has the following fixed, 23-character format: dd-mmm-yyyy hh:mm:ss.cc When the current day of the month is any of the values 1 to 9, the first character in the returned string is a blank character. The time portion of the string is always in character position 13, at an offset of 12 characters from the beginning of the string. Note that you must use the assignment operator (=) to preserve the blank character in the returned string. If you use the string assignment operator (:=), the leading blank is dropped.
Example
$ OPEN/WRITE OUTFILE DATA.DAT
$ TIME_STAMP = F$TIME()
$ WRITE OUTFILE TIME_STAMP
This example shows how to use the F$TIME function to time-stamp
a file that you create from a command procedure. OUTFILE is
the logical name for the file DATA.DAT, which is opened for
writing. The F$TIME function returns the current date and time
string, and assigns this string to the symbol TIME_STAMP. The
WRITE command writes the date and time string to OUTFILE.
F$TRNLNM
Translates a logical name and returns the equivalence name string,
or the requested attributes of the logical name specified.
Format
F$TRNLNM(logical-name [,table] [,index] [,mode] [,case]
[,item])
Additional information available:
Return Valuelogical-nametableindexmodecaseitem
Examples
Return Value
The equivalence name or attribute of the specified logical
name. The return value can be a character string or an integer,
depending on the arguments you specify with the F$TRNLNM function.
If no match is found, a null string ("") is returned.
logical-name
Specifies a character string containing the logical name to be translated.
table
Specifies a character string containing the logical name table or tables that the F$TRNLNM function should search to translate the logical name. The table argument must be a logical name that translates to a logical name table or to a list of table names. If you do not specify a table, the default value is LNM$DCL_ LOGICAL. That is, the F$TRNLNM function searches the tables whose names are equated to the logical name LNM$DCL_LOGICAL. Unless LNM$DCL_LOGICAL has been redefined for your process, the F$TRNLNM function searches the process, job, group, and system logical name tables, in that order, and returns the equivalence name for the first match found.
index
Specifies the number of the equivalence name to be returned if the logical name has more than one translation. The index refers to the equivalence strings in the order the names were listed when the logical name was defined. The index begins with zero; that is, the first name in a list of equivalence names is referenced by the index zero. If you do not specify the index argument, the default is zero.
mode
Specifies a character string containing one of the following access modes for the translation: USER (default), SUPERVISOR, EXECUTIVE, or KERNEL. The F$TRNLNM function starts by searching for a logical name created with the access mode specified in the mode argument. If it does not find a match, the F$TRNLNM function searches for the name created with each inner access mode and returns the first match found. For example, two logical names can have the same name, but one name can be created with user access mode and the other name with executive access mode. If the mode argument is USER, the F$TRNLNM function returns the equivalence string for the user-mode, not the executive-mode, logical name.
case
Specifies the type of case translation to be performed. Specify
the case argument as either of the following character strings:
CASE_BLIND (default) or CASE_SENSITIVE.
If the translation is case blind, the F$TRNLNM function first
searches for a logical name with characters of the same case as
the logical-name argument. If no match is found, the F$TRNLNM
function searches for an uppercase version of the logical-name
argument and the logical names it is searching. The result of the
first successful translation is returned.
If the translation is case sensitive, the F$TRNLNM function
searches only for a logical name with characters of the same
case as the logical-name argument. If no exact match is found,
the F$TRNLNM function returns a null string ("").
item
Specifies a character string containing the type of information
that F$TRNLNM should return about the specified logical name.
Specify one of the following items:
Return
Item Type Information Returned
ACCESS_MODE String One of the following access modes
associated with the logical name: USER,
SUPERVISOR, EXECUTIVE, KERNEL.
CONCEALED String TRUE or FALSE to indicate whether the
CONCEALED attribute was specified with the
/TRANSLATION_ATTRIBUTES qualifier when the
logical name was created. The CONCEALED
attribute is used to create a concealed
logical name.
CONFINE String TRUE or FALSE to indicate whether the
logical name is confined. If the logical
name is confined (TRUE), then the name is
not copied to subprocesses. If the logical
name is not confined (FALSE), then the
name is copied to subprocesses.
CRELOG String TRUE or FALSE to indicate whether the
logical name was created with the $CRELOG
system service or with the $CRELNM system
service, using the CRELOG attribute.
If the logical name was created with
the $CRELOG system service or with
the $CRELNM system service, using the
CRELOG attribute, then TRUE is returned.
Otherwise, FALSE is returned.
LENGTH Integer Length of the equivalence name associated
with the specified logical name. If the
logical name has more than one equivalence
name, the F$TRNLNM function returns the
length of the name specified by the index
argument.
MAX_INDEX Integer The largest index defined for the logical
name. The index shows how many equivalence
names are associated with a logical name.
The index is zero based; that is, the
index zero refers to the first name in a
list of equivalence names.
NO_ALIAS String TRUE or FALSE to indicate whether the
logical name has the NO_ALIAS attribute.
The NO_ALIAS attribute means that a
logical name must be unique within outer
access mode.
TABLE String TRUE or FALSE to indicate whether the
logical name is the name of a logical name
table.
TABLE_NAME String Name of the table where the logical name
was found.
TERMINAL String TRUE or FALSE to indicate whether the
TERMINAL attribute was specified with the
/TRANSLATION_ATTRIBUTES qualifier when the
logical name was created. The TERMINAL
attribute indicates that the logical
name is not a candidate for iterative
translation.
VALUE String Default. The equivalence name associated
with the specified logical name. If the
logical name has more than one equivalence
name, the F$TRNLNM function returns the
name specified by the index argument.
Examples
1. $ SAVE_DIR = F$TRNLNM("SYS$DISK")+F$DIRECTORY()
.
.
.
$ SET DEFAULT 'SAVE_DIR'
The assignment statement concatenates the values returned
by the F$DIRECTORY and F$TRNLNM functions, and assigns the
resulting string to the symbol SAVE_DIR. The symbol SAVE_DIR
consists of a full device and directory name string.
The argument SYS$DISK is enclosed in quotation marks (" ")
because it is a character string. (The command interpreter
treats all arguments that begin with alphabetic characters
as symbols or lexical functions, unless the arguments are
enclosed in quotation marks.) None of the optional arguments
is specified, so the F$TRNLNM function uses the defaults.
At the end of the command procedure, the original default
directory is reset. When you reset the directory, you must
place single quotation marks (' ') around the symbol SAVE_DIR
to force symbol substitution.
2. $ DEFINE/TABLE=LNM$GROUP TERMINAL 'F$TRNLNM("SYS$OUTPUT")'
This example shows a line from a command procedure that (1)
uses the F$TRNLNM function to determine the name of the current
output device and (2) creates a group logical name table entry
based on the equivalence string.
You must enclose the argument SYS$OUTPUT in quotation marks
because it is a character string.
Also, in this example you must enclose the F$TRNLNM function
in single quotation marks to force the lexical function to be
evaluated. Otherwise, the DEFINE command does not automatically
evaluate the lexical function.
F$TYPE
Returns the data type of a symbol.
Format
F$TYPE(symbol-name)
Additional information available:
Return Valuesymbol-nameExamples
Return Value
The string INTEGER is returned if the symbol is equated to an
integer, or if the symbol is equated to a string whose characters
form a valid integer.
If the symbol has been produced by a call to the F$CONTEXT
function with a context type of PROCESS or by a call to the F$PID
function, the string returned is PROCESS_CONTEXT. A symbol retains
this type until F$CONTEXT is called with the symbol and the CANCEL
keyword, or until a null string ("") is returned by a call to
F$PID.
Similarly, the return value is the string CLUSTER_SYSTEM_CONTEXT
for symbols created by the F$CSID function.
If the symbol is a context symbol, then the return value will be
one of the following types:
Symbol Type Lexical Creating Symbol
PROCESS_CONTEXT F$PID or F$CONTEXT (with PROCESS context-
type)
CLUSTER_SYSTEM_CONTEXT F$CSID
The string STRING is returned if the symbol is equated to a
character string whose characters do not form a valid integer
or whose type is not a context.
If the symbol is undefined, a null string is returned.
symbol-name
Specifies the name of the symbol to be evaluated.
Examples
1. $ NUM = "52"
$ TYPE = F$TYPE(NUM)
$ SHOW SYMBOL TYPE
TYPE = "INTEGER"
This example uses the F$TYPE function to determine the data
type of the symbol NUM. NUM is equated to the character
string "52". Because the characters in the string form a valid
integer, the F$TYPE function returns the string INTEGER.
2. $ NUM = 52
$ TYPE = F$TYPE(NUM)
$ SHOW SYMBOL TYPE
TYPE = "INTEGER"
In this example, the symbol NUM is equated to the integer 52.
The F$TYPE function shows that the symbol has an integer data
type.
3. $ CHAR = "FIVE"
$ TYPE = F$TYPE(CHAR)
$ SHOW SYMBOL TYPE
TYPE = "STRING"
In this example, the symbol CHAR is equated to the character
string FIVE. Because the characters in this string do not form
a valid integer, the F$TYPE function shows that the symbol has
a string value.
4. $ x = F$CONTEXT("PROCESS",CTX,"USERNAME","SMITH")
$ TYPE = F$TYPE(CTX)
$ SHOW SYMBOL TYPE
TYPE = "PROCESS_CONTEXT"
$ x = F$CONTEXT("PROCESS",CTX,"CANCEL")
$ TYPE = F$TYPE(CTX)
$ SHOW SYMBOL TYPE
TYPE = ""
In this example, the F$TYPE function returns the string
PROCESS_CONTEXT because the symbol has been produced by a call
to the F$CONTEXT function with a context type of PROCESS. The
symbol returns this type until F$CONTEXT is called with the
symbol and the selection-item argument value CANCEL.
F$USER
Returns the current user identification code (UIC) in named format
as a character string. The F$USER function has no arguments, but
must be followed by parentheses.
Format
F$USER()
Additional information available:
Return Value
A character string containing the current UIC, including brackets ([ ]). The UIC is returned in the format [group-identifier, member-identifier].
Example
$ UIC = F$USER()
$ SHOW SYMBOL UIC
UIC = "[GROUP6,JENNIFER]"
In this example the F$USER function returns the current user
identification code and assigns it to the symbol UIC.
F$VERIFY
Returns an integer value indicating whether the procedure
verification setting is currently on or off. If used with
arguments, the F$VERIFY function can turn the procedure and image
verification settings on or off. You must include the parentheses
after the F$VERIFY function whether or not you specify arguments.
Format
F$VERIFY([procedure-value] [,image-value])
Additional information available:
Return Valueprocedure-valueimage-valueDescriptionExamples
Return Value
The integer 0 if the procedure verification setting is off, or the integer 1 if the procedure verification setting is on.
procedure-value
Specifies an integer expression with a value of 1 to turn procedure verification on, or a value of 0 to turn procedure verification off. When procedure verification is on, each DCL command line in the command procedure is displayed on the output device. Procedure verification allows you to verify that each command is executing correctly. If you use the procedure-value argument, the function first returns the current procedure verification setting. Then the command interpreter turns the procedure verification on or off, as specified by the argument.
image-value
Specifies an integer expression with a value of 1 to turn image verification on, or a value of 0 to turn image verification off. When image verification is on, data lines in the command procedure are displayed on the output device.
Description
The lexical function F$VERIFY returns an integer value indicating
whether the procedure verification setting is currently on or
off. If used with arguments, the F$VERIFY function can turn the
procedure and image verification settings on or off. You must
include the parentheses after the F$VERIFY function whether or not
you specify arguments.
Using the F$VERIFY function in command procedures allows you to
test the current procedure verification setting. For example,
a command procedure can save the current procedure verification
setting before changing it and then later restore the setting. In
addition, you can construct a procedure that does not display
(or print) commands, regardless of what the initial state of
verification is.
When you use the F$VERIFY function, you can specify zero, one,
or two arguments. If you do not specify any arguments, neither
of the verification settings is changed. If you specify only the
procedure-value argument, both procedure and image verification
are turned on (if the value is 1) or off (if the value is 0).
If you specify both arguments, procedure and image verification
are turned on or off independently. If you specify the image-value
argument alone, only image verification is turned on or off. If
you specify the image-value argument alone, you must precede the
argument with a comma (,).
You can also use the F$ENVIRONMENT function with VERIFY_PROCEDURE
or VERIFY_IMAGE as the argument. With the F$ENVIRONMENT function,
you can determine either the procedure or image verification
setting; the F$VERIFY function determines only the procedure
verification setting.
DCL performs the F$VERIFY function even if it appears after a
comment character, if it is enclosed in single quotation marks
(' '). This is the only processing that DCL performs within a
comment.
Examples
1. $ SAVE_PROC_VERIFY = F$ENVIRONMENT("VERIFY_PROCEDURE")
$ SAVE_IMAGE_VERIFY = F$ENVIRONMENT("VERIFY_IMAGE")
$ SET NOVERIFY
.
.
.
$ TEMP = F$VERIFY(SAVE_PROC_VERIFY, SAVE_IMAGE_VERIFY)
This example shows an excerpt from a command procedure.
The first assignment statement assigns the current
procedure verification setting to the symbol SAVE_
PROC_VERIFY. The second assignment statement assigns
the current image verification setting to the symbol
SAVE_IMAGE_VERIFY.
Then, the SET NOVERIFY command disables procedure and image
verification. Later, the F$VERIFY function resets the
verification settings, using the original values (equated to
the symbols SAVE_PROC_VERIFY and SAVE_IMAGE_VERIFY). The symbol
TEMP contains the procedure verification before it is changed
with the F$VERIFY function. (In this example the value of TEMP
is not used.)
2. $ VERIFY = F$VERIFY(0)
.
.
.
$ IF VERIFY .EQ. 1 THEN SET VERIFY
This example shows an excerpt from a command procedure that
uses the F$VERIFY function to save the current procedure
verification setting and to turn both procedure and image
verification off. At the end of the command procedure, if
procedure verification was originally on, both the procedure
and image verification are turned on.
Line editing
Your terminal has special keys that allow you to recall and edit
previous commands. These keys are described below. Note that some
of these keys may not be available on your keyboard.
Recalling Commands
------------------
The system saves and allows you to access up to 20 of your most recently
entered commands. It saves less than 20 if your commands are very long.
Use the UP-ARROW or CTRL/B keys to recall previously entered commands.
Use the DOWN-ARROW key to reexamine a command that you had retrieved
using UP-ARROW.
If you are supplying commands or data to a program or utility, the
system saves and allows you to access only your single most recently
entered command.
Editing Commands
----------------
To enable the editing keys, execute the command
SET TERMINAL/LINE_EDITING
Append /OVERSTRIKE or /INSERT to the command to specify the default
editing mode that you prefer. /OVERSTRIKE causes a character that you
type to be written over the character that the cursor is currently
pointing at. /INSERT causes the character to be inserted before the
cursor.
Edit Key Function
-------- --------
CTRL/A or Switches between overstrike mode and insert mode. The
F14 default mode is reset at the beginning of each line.
CTRL/D or Moves the cursor one character to the left.
LEFT-ARROW
CTRL/E Moves the cursor to the end of the line.
CTRL/F or Moves the cursor one character to the right.
RIGHT-ARROW
CTRL/H or Moves the cursor to the beginning of the line.
BACKSPACE or
F12
CTRL/J or Deletes the word to the left of the cursor.
LINEFEED or
F13
CTRL/U Deletes characters from the beginning of the line to the
cursor.
Queues
The following DCL commands can be used to control print and batch queues
and the entries in them.
ASSIGN/MERGE Move jobs from one queue to another
ASSIGN/QUEUE Assign a queue to a device
DEASSIGN/QUEUE Deassign a queue from a device
DELETE/ENTRY Delete a pending entry from a queue
DELETE/QUEUE Delete a queue and all its entries
INITIALIZE/QUEUE Create and initialize a queue
PRINT Place an entry in a print queue
SET ENTRY Change the status of a pending entry in a queue
(supersedes the SET QUEUE/ENTRY command)
SET QUEUE/ENTRY Change the status of a pending entry in a queue
SHOW QUEUE Display status of entries in a queue
START/QUEUE Start or restart a queue
STOP/QUEUE Control queue or current entry in it
STOP/REQUEUE Stop and requeue an entry in a print queue
SUBMIT Place an entry in a batch queue
SYNCHRONIZE Wait for completion of a batch entry
RTL Routines
The VAX Run-Time Library is a collection of procedures available to native mode images at run time. These library procedures are common to all native mode images, regardless of the language processor used to compile or assemble the program.
Additional information available:
DNS$DTK$LIB$MTH$OTS$PPL$SMG$
STR$
DNS$
Additional information available:
DNS$APPEND_SIMPLENAME_TO_RIGHTDNS$COMPARE_FULLNAME
DNS$COMPARE_SIMPLENAMEDNS$CONCATENATE_NAMEDNS$COUNT_SIMPLENAMES
DNS$CVT_DNSADDRESS_TO_BINARYDNS$CVT_DNSADDRESS_TO_NODENAME
DNS$CVT_NODENAME_TO_DNSADDRESSDNS$CVT_TO_USERNAME_STRING
DNS$PARSE_USERNAME_STRINGDNS$REMOVE_FIRST_SET_VALUEDNS$REMOVE_LEFT_SIMPLENAME
DNS$REMOVE_RIGHT_SIMPLENAME
DNS$APPEND_SIMPLENAME_TO_RIGHT
The Append a Simple Name to the End of a Full Name routine adds an
opaque simple name to the end of an opaque full name to create a
new full name.
Format
DNS$APPEND_SIMPLENAME_TO_RIGHT
fullname ,simplename ,resulting-fullname ,resulting-length
Arguments
fullname
VMS Usage: char_string
type: character string
access: read only
mechanism: by descriptor
The opaque full name gaining a new simple name. The fullname
argument is the address of a descriptor pointing to the opaque
full name that is to be extended.
simplename
VMS Usage: char_string
type: character string
access: read only
mechanism: by descriptor
The opaque simple name that is appended. The simplename argument
is the address of a descriptor pointing to an opaque simple name
that is to be appended to the full name, thus creating a new full
name.
resulting-fullname
VMS Usage: char_string
type: character string
access: write only
mechanism: by descriptor
The new full name. The resulting-fullname argument is the address
of a descriptor that points to the buffer that receives the new
full name. This buffer can be the same as the buffer referred
to by the fullname argument; however, the descriptors must be
separate.
resulting-length
VMS Usage: word_unsigned
type: word (unsigned)
access: write only
mechanism: by reference
The length of the new full name. The resulting-length argument
is the address of a word that receives the length of the new full
name found in resulting-fullname.
DNS$COMPARE_FULLNAME
The Compare Full Names routine compares two opaque full names and
returns the result.
Format
DNS$COMPARE_FULLNAME fullname1 ,fullname2
Arguments
fullname1
VMS Usage: char_string
type: character string
access: read only
mechanism: by descriptor
One opaque full name. The fullname1 argument is the address of a
descriptor pointing to an opaque full name.
fullname2
VMS Usage: char_string
type: character string
access: read only
mechanism: by descriptor
One opaque full name. The fullname2 argument is the address of a
descriptor pointing to an opaque full name.
DNS$COMPARE_SIMPLENAME
The Compare Two Simple Names routine compares two simple names,
without considering case.
Format
DNS$COMPARE_SIMPLENAME simplename1 ,simplename2
Arguments
simplename1
VMS Usage: char_string
type: character string
access: read only
mechanism: by descriptor
An opaque simple name. The simplename1 argument is the address of
a descriptor pointing to the first simple name.
simplename2
VMS Usage: char_string
type: character string
access: read only
mechanism: by descriptor
An opaque simple name. The simplename2 argument is the address of
a descriptor pointing to the second simple name.
DNS$CONCATENATE_NAME
The Join Two Names routine joins two opaque full names to form a
new full name.
Format
DNS$CONCATENATE_NAME
fullname1 ,fullname2 ,resulting-fullname ,resulting-length
Arguments
fullname1
VMS Usage: char_string
type: character string
access: read only
mechanism: by descriptor
The opaque full name to be joined. The fullname1 argument is the
address of a descriptor pointing to the opaque full name.
fullname2
VMS Usage: char_string
type: character string
access: read only
mechanism: by descriptor
The opaque full name appended to fullname1. The fullname2 argument
is the address of a descriptor pointing to the full name to be
appended.
resulting-fullname
VMS Usage: char_string
type: character string
access: write only
mechanism: by descriptor
The buffer where the new full name will be written. The resulting-
fullname argument is the address of a descriptor pointing to the
buffer. This buffer can be the same as the buffer referred to by
the fullname1 argument; however, the descriptors must be separate.
resulting-length
VMS Usage: word_unsigned
type: word (unsigned)
access: write only
mechanism: by reference
The length of the new full name. The resulting-length argument
is the address of a word that receives the length of the new full
name found in resulting-fullname.
DNS$COUNT_SIMPLENAMES
The Count the Simple Names in a Full Name routine counts the
number of simple names contained in an opaque full name.
Format
DNS$COUNT_SIMPLENAMES fullname ,count
Arguments
fullname
VMS Usage: char_string
type: character string
access: read only
mechanism: by descriptor
The full name to be counted. The fullname argument is the address
of a descriptor pointing to the full name that is to be examined
for the simple names it contains.
count
VMS Usage: word_unsigned
type: word (unsigned)
access: write only
mechanism: by reference
The number of simple names found in the full name. The count
argument is the address of a word that receives the number of
simple names.
DNS$CVT_DNSADDRESS_TO_BINARY
The Convert a DNS Address to a Phase IV Binary Address routine
takes a DNS address and returns the DECnet Phase IV node address.
Format
DNS$CVT_DNSADDRESS_TO_BINARY dnsaddress ,binary
Arguments
dnsaddress
VMS Usage: char_string
type: character string
access: read only
mechanism: by descriptor
The DNS address. The dnsaddress argument is the address of a
descriptor pointing to the DNS address.
binary
VMS Usage: word_unsigned
type: word (unsigned)
access: write only
mechanism: by reference
The DECnet Phase IV address found in the DNS address structure.
The binary argument is the address of a word containing the 16-bit
Phase IV address of the node.
DNS$CVT_DNSADDRESS_TO_NODENAME
The Convert a DNS Address to a Node Name routine takes a DNS
address and returns a DECnet Phase IV node name.
Format
DNS$CVT_DNSADDRESS_TO_NODENAME
dnsaddress ,nodename ,resulting-length
Arguments
dnsaddress
VMS Usage: char_string
type: character string
access: read only
mechanism: by descriptor
The DNS address. The dnsaddress argument is the address of a
descriptor pointing to the DNS address.
nodename
VMS Usage: char_string
type: character string
access: write only
mechanism: by descriptor
The DECnet Phase IV node name. The nodename argument is the
address of a descriptor pointing to the Phase IV node name. The
memory buffer referenced by the DSC$A_POINTER portion of this
descriptor must be large enough to contain the entire Phase IV
node name string, which is up to six bytes long.
resulting-length
VMS Usage: word_unsigned
type: word (unsigned)
access: write only
mechanism: by reference
The length of the node name (in bytes) after conversion. The
resulting-length argument is a word containing the length of the
node name (in bytes) after conversion.
DNS$CVT_NODENAME_TO_DNSADDRESS
The Convert a Node Name to a DNS Address routine takes a DECnet
Phase IV node name and returns a DNS address.
Format
DNS$CVT_NODENAME_TO_DNSADDRESS
nodename ,dnsaddress ,resulting-length
Arguments
nodename
VMS Usage: char_string
type: character string
access: read only
mechanism: by descriptor
The DECnet Phase IV node name. The nodename argument is the
address of a descriptor pointing to the node name. This routine
creates a DNS address containing the node address of the given
Phase IV node name.
dnsaddress
VMS Usage: char_string
type: character string
access: write only
mechanism: by descriptor
The address of a buffer containing the DNS address. The dnsaddress
argument is the address of a descriptor pointing to the buffer
address.
resulting-length
VMS Usage: word_unsigned
type: word (unsigned)
access: write only
mechanism: by reference
The length of the DNS address after conversion. The resulting-
length argument is a word containing the length of the address.
DNS$CVT_TO_USERNAME_STRING
The Convert an Opaque User Name to a String routine converts an
opaque DECnet Phase IV user name into a username string.
Format
DNS$CVT_TO_USERNAME_STRING
fullname ,username ,resulting-length
Arguments
fullname
VMS Usage: char_string
type: character string
access: read only
mechanism: by descriptor
The opaque full name for the DECnet Phase IV user name. The
fullname argument is the address of a descriptor pointing to the
name.
username
VMS Usage: char_string
type: character string
access: write only
mechanism: by descriptor
The name converted to DECnet Phase IV format (node::user). The
username argument is the address of a descriptor pointing to a
buffer containing the converted name.
resulting-length
VMS Usage: word_unsigned
type: word (unsigned)
access: write only
mechanism: by reference
The length of the converted user name. The resulting-length
argument is the address of a word containing the length.
DNS$PARSE_USERNAME_STRING
The Convert a User Name from String to Opaque routine converts a
DECnet Phase IV user name to an opaque full name.
Format
DNS$PARSE_USERNAME_STRING
user-string ,phase4-name ,resulting-length
[,next-character-pointer]
Arguments
user-string
VMS Usage: char_string
type: character string
access: read only
mechanism: by descriptor
The name string to convert. The user-string argument is the
address of a descriptor pointing to the DECnet Phase IV username
string, which is in the format node::user.
phase4-name
VMS Usage: char_string
type: character string
access: write only
mechanism: by descriptor
The opaque full name resulting from conversion. The phase4-name
argument is the address of a descriptor pointing to the buffer
that is to contain an opaque full name representing a user name on
a Phase IV node.
resulting-length
VMS Usage: word_unsigned
type: word (unsigned)
access: write only
mechanism: by reference
The length of the opaque full name. The resulting-length argument
is the address of a word holding the length of the name returned
in phase4-name.
next-character-pointer
VMS Usage: address
type: address
access: write only
mechanism: by reference
The character following the DNS name extracted from user-string.
The next-character-pointer argument is the address of the
character following the DNS name. When you use this argument,
DNS$PARSE_USERNAME_STRING returns DNS$_INVALIDNAME when it
encounters an invalid name. In such a case, next-character-pointer
points to the first character in the name that is invalid.
DNS$REMOVE_FIRST_SET_VALUE
The Remove a Value from a Set routine extracts the first value
from a set and returns the value with its creation time-stamping
(UID).
Format
DNS$REMOVE_FIRST_SET_VALUE
set [,value] [,value-length] [,uid] [,uid-length] [,newset]
[,newset-length]
Arguments
set
VMS Usage: char_string
type: character string
access: read only
mechanism: by descriptor
The set from which the value is extracted. The set argument is the
address of a descriptor pointing to the set.
value
VMS Usage: char_string
type: character string
access: write only
mechanism: by descriptor
The value extracted from the set. The value argument is the
address of a descriptor pointing to a buffer containing the value.
value-length
VMS Usage: word_unsigned
type: word (unsigned)
access: write only
mechanism: by reference
The length of the value. The value-length argument is the address
of a word holding the length of the value placed in value.
uid
VMS Usage: char_string
type: character string
access: write only
mechanism: by descriptor
The buffer holding the creation time-stamping (UID) of the
extracted value. The uid argument is the address of a descriptor
pointing to the buffer.
uid-length
VMS Usage: word_unsigned
type: word (unsigned)
access: write only
mechanism: by reference
The length of the UID placed in uid. The uid-length argument is
the address of a word holding the length.
newset
VMS Usage: char_string
type: character string
access: write only
mechanism: by descriptor
The opaque set without the first value. The newset argument is the
address of a descriptor pointing to a buffer containing that set.
The buffer can be the same as the one given in the set argument.
newset-length
VMS Usage: word_unsigned
type: word (unsigned)
access: write only
mechanism: by reference
The length of the new set copied to the newset buffer. The newset-
length argument is the address of a word that receives the length.
DNS$REMOVE_LEFT_SIMPLENAME
The Remove the Simple Name on the Left from the Full Name routine
removes the leftmost simple name from an opaque full name. It
returns both the simple name stripped and the new full name that
results from the operation.
Format
DNS$REMOVE_LEFT_SIMPLENAME
fullname [,resulting-fullname] [,resulting-fullname-length]
[,resulting-simplename] [,resulting-simplename-length]
Arguments
fullname
VMS Usage: char_string
type: character string
access: read only
mechanism: by descriptor
The opaque full name to strip. The fullname argument is the
address of a descriptor pointing to the opaque full name to strip.
If the full name does not contain any simple names, the routine
returns a value of 0 in cond_value.
resulting-fullname
VMS Usage: char_string
type: character string
access: write only
mechanism: by descriptor
The opaque full name resulting from the operation. The resulting-
fullname argument is the address of a descriptor pointing to the
buffer containing the resulting opaque full name. This buffer can
be the same as the buffer referred to by the fullname argument;
however, the descriptors must be separate.
resulting-fullname-length
VMS Usage: word_unsigned
type: word (unsigned)
access: write only
mechanism: by reference
The length of the full name that is returned. The resulting-
fullname-length argument is the address of a word receiving the
length of the full name returned in resulting-fullname.
resulting-simplename
VMS Usage: char_string
type: character string
access: write only
mechanism: by descriptor
The simple name stripped from fullname. The resulting-simplename
argument is the address of a descriptor pointing to the buffer
containing the opaque simple name that was stripped.
resulting-simplename-length
VMS Usage: word_unsigned
type: word (unsigned)
access: write only
mechanism: by reference
The length of the simple name. The resulting-simplename-length
argument is the address of a word that receives the length of the
simple name returned in resulting-simplename.
DNS$REMOVE_RIGHT_SIMPLENAME
The Remove the Simple Name on the Right from the Full Name routine
removes the rightmost simple name from an opaque full name. It
returns both the simple name stripped and the new full name that
results from the operation.
Format
DNS$REMOVE_RIGHT_SIMPLENAME
fullname [,resulting-fullname] [,resulting-fullname-length]
[,resulting-simplename] [,resulting-simplename-length]
Arguments
fullname
VMS Usage: char_string
type: character string
access: read only
mechanism: by descriptor
The opaque full name to strip. The fullname argument is the
address of a descriptor pointing to the opaque full name to strip.
When the opaque full name does not contain any simple names, the
routine returns a value of 0 in cond_value.
resulting-fullname
VMS Usage: char_string
type: character string
access: write only
mechanism: by descriptor
The opaque full name resulting from the operation. The resulting-
fullname argument is the address of a descriptor pointing to a
buffer containing the resulting opaque full name. This buffer can
be the same as the buffer referred to by the fullname argument;
however, the descriptors must be separate.
resulting-fullname-length
VMS Usage: word_unsigned
type: word (unsigned)
access: write only
mechanism: by reference
The length of the full name returned in resulting-fullname.
The resulting-fullname-length argument is the address of a word
that receives the length of the full name returned in resulting-
fullname.
resulting-simplename
VMS Usage: char_string
type: character string
access: write only
mechanism: by descriptor
A buffer containing the opaque simple name stripped from fullname.
The resulting-simplename argument is the address of a descriptor
pointing to the buffer.
resulting-simplename-length
VMS Usage: word_unsigned
type: word (unsigned)
access: write only
mechanism: by reference
The length of the simple name. The resulting-simplename-length
argument is the address of a word receiving the length of the
simple name returned in resulting-simplename.
DTK$
Additional information available:
DTK$ANSWER_PHONEDTK$CHECK_HDWR_STATUSDTK$DIAL_PHONE
DTK$HANGUP_PHONEDTK$INITIALIZEDTK$LOAD_DICTIONARY
DTK$READ_KEYSTROKEDTK$READ_STRINGDTK$RETURN_LAST_INDEX
DTK$SET_INDEXDTK$SET_KEYPAD_MODEDTK$SET_LOGGING_MODE
DTK$SET_MODEDTK$SET_SPEECH_MODEDTK$SET_TERMINAL_MODE
DTK$SET_VOICEDTK$SPEAK_FILEDTK$SPEAK_PHONEMIC_TEXT
DTK$SPEAK_TEXTDTK$SPELL_TEXTDTK$TERMINATE
DTK$ANSWER_PHONE
The Wait for Phone to Ring and Answer routine waits for the phone
connected to the DECtalk device to ring and then answers it.
Format:
DTK$ANSWER_PHONE voice-id [,number-of-rings] [,text] [,timeout]
Arguments:
voice-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Voice identifier of the DECtalk device. The voice-id argument is
the address of an unsigned longword containing this identifier. The
voice identifier is returned by the DTK$INITIALIZE routine.
number-of-rings
VMS usage: longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Number of rings DECtalk waits for before answering the phone. The
optional number-of-rings argument is the address of a signed
longword containing this number. The default is 1 ring.
text
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
Text that DECtalk speaks after answering the phone. The optional
text argument is the address of a descriptor pointing to the text.
timeout
VMS usage: longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Number of seconds that DECtalk allows the phone to ring before
answering. The optional timeout argument is the address of a signed
longword containing this timeout value. There is no default value.
DTK$CHECK_HDWR_STATUS
The Check Hardware Status routine checks the DECtalk hardware for
hardware malfunctions.
Format:
DTK$CHECK_HDWR_STATUS voice-id ,hdwr-status
Arguments:
voice-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Voice identifier of the DECtalk. The voice-id argument is the
address of an unsigned longword containing this identifier. The
voice identifier is returned by the DTK$INITIALIZE routine.
hdwr-status
VMS usage: mask_longword
type: longword (unsigned)
access: write only
mechanism: by reference
Receives the hardware status of the DECtalk machine. The
hdwr-status argument is the address of an unsigned longword bit mask
that receives the status.
DTK$DIAL_PHONE
The Dial the Telephone routine dials the specified number on the
telephone.
Format:
DTK$DIAL_PHONE voice-id ,phone-number [,dial-mode] [,text]
[,timeout]
Arguments:
voice-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Voice identifier of the DECtalk machine. The voice-id argument is
the address of an unsigned longword containing this identifier. The
voice identifier is returned by the DTK$INITIALIZE routine.
phone-number
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
Phone number to dial. The phone-number argument is the address of a
descriptor pointing to the specified phone number.
dial-mode
VMS usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
Mode to use when dialing the phone. The optional dial-mode argument
is the address of an unsigned longword containing this mode.
text
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
Text to be spoken after the phone is answered. The text argument is
the address of a descriptor pointing to the specified text.
timeout
VMS usage: longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Number of seconds to wait for the phone to be answered. The
optional timeout argument is the address of a signed longword
containing this timeout value. If omitted, DECtalk dials the phone
and then returns control to the calling program immediately.
DTK$HANGUP_PHONE
The Hang Up the Phone routine speaks an optional message and then
hangs up the phone.
Format:
DTK$HANGUP_PHONE voice-id [,text]
Arguments:
voice-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Voice identifier of the DECtalk device. The voice-id argument is
the address of an unsigned longword containing this identifier. The
voice identifier is returned by the DTK$INITIALIZE routine.
text
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
Text to be spoken before hanging up the phone. The optional text
argument is the address of a descriptor pointing to the specified
text.
DTK$INITIALIZE
The Initialize DECtalk routine initializes a DECtalk device and
returns the device's assigned voice identifier.
Format:
DTK$INITIALIZE voice-id ,output-device [,device-type]
Arguments:
voice-id
VMS usage: identifier
type: longword (unsigned)
access: write only
mechanism: by reference
Voice identifier of the newly created DECtalk device. The voice-id
argument is the address of an unsigned longword that receives this
identifier.
output-device
VMS usage: device_name
type: character string
access: read only
mechanism: by descriptor
File specification or logical name to which the output associated
with the DECtalk device is written. The output-device argument is
the address of a descriptor pointing to this logical name.
device-type
VMS usage: longword_signed
type: longword (signed)
access: write only
mechanism: by reference
Device type of the newly created DECtalk device. The optional
device-type argument is the address of a signed longword that
receives the device-type information. The two valid device types
are:
DTK$K_DTC_01 For DECtalk I.
DTK$K_DTC_03 For DECtalk III.
DTK$LOAD_DICTIONARY
The Load a Word into the DECtalk Dictionary routine loads a phonemic
definition of a word into the DECtalk dictionary.
Format:
DTK$LOAD_DICTIONARY voice-id ,text ,substitution
Arguments:
voice-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Voice identifier of the DECtalk device. The voice-id argument is
the address of an unsigned longword containing this identifier. The
voice identifier is returned by the DTK$INITIALIZE routine.
text
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
Word to be loaded into the DECtalk dictionary. The text argument is
the address of a descriptor pointing to the specified word.
substitution
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
Phonemic definition of the word specified by the text argument. The
substitution argument is the address of a descriptor pointing to the
phonemic representation of the specified word.
DTK$READ_KEYSTROKE
The Read a Key Entered on the Keypad routine reads a key entered on
the phone keypad.
Format:
DTK$READ_KEYSTROKE voice-id ,key-code [,prompt-string]
[,timeout]
Arguments:
voice-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Voice identifier of the DECtalk device. The voice-id argument is
the address of an unsigned longword containing this identifier. The
voice identifier is returned by the DTK$INITIALIZE routine.
key-code
VMS usage: longword_signed
type: longword (signed)
access: write only
mechanism: by reference
The DTK$K_TRM_xxxx code for the key entered on the keypad. The
key-code argument is the address of a signed longword that receives
this code. The valid codes are listed in DTKDEF.
prompt-string
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
Text to be spoken before waiting for input. The optional
prompt-string argument is the address of a descriptor pointing to
this text.
timeout
VMS usage: longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Number of seconds to wait for input. The optional timeout argument
is the address of a signed longword containing the specified number
of seconds the DECtalk device waits for input. If the timeout
argument is omitted, DTK$READ_KEYSTROKE waits for input
indefinitely.
DTK$READ_STRING
The Read a Series of Keys Entered on the Keypad routine reads a
series of keys entered on the phone keypad.
Format:
DTK$READ_STRING voice-id ,resultant-string [,prompt-string]
[,timeout] [,longword-integer-termin-code]
Arguments:
voice-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Voice identifier of the DECtalk device. The voice-id argument is
the address of an unsigned longword containing this identifier. The
voice identifier is returned by the DTK$INITIALIZE routine.
resultant-string
VMS usage: char_string
type: character string
access: write only
mechanism: by descriptor
String into which the keys being read are written. The
resultant-string argument is the address of a descriptor pointing to
this string.
prompt-string
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
Text to be spoken before waiting for input. The optional
prompt-string argument is the address of a descriptor pointing to
this text.
timeout
VMS usage: longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Number of seconds DECtalk waits for input. The optional timeout
argument is the address of a signed longword containing the number
of seconds DECtalk waits for input. If the timeout argument is
omitted, DTK$READ_STRING waits for input indefinitely.
longword-integer-termin-code
VMS usage: longword_signed
type: longword (signed)
access: write only
mechanism: by reference
The DTK$K_TRM_xxxx code for terminating key entered. The optional
longword-integer-termin-code argument is the address of a signed
longword that receives this code. The valid codes are located in
DTKDEF.
DTK$RETURN_LAST_INDEX
The Return Last Index Spoken routine returns the last index spoken.
Format:
DTK$RETURN_LAST_INDEX voice-id ,p-index
Arguments:
voice-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Voice identifier of the DECtalk device. The voice-id argument is
the address of an unsigned longword containing this identifier. The
voice identifier is returned by the DTK$INITIALIZE routine.
p-index
VMS usage: longword_signed
type: longword (signed)
access: write only
mechanism: by reference
Index to be returned. The p-index argument is the address of a
signed longword that receives the index identifier.
DTK$SET_INDEX
The Insert an Index at the Current Position routine inserts an index
into the current output stream.
Format:
DTK$SET_INDEX voice-id ,p-index
Arguments:
voice-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Voice identifier of the DECtalk device. The voice-id argument is
the address of an unsigned longword containing this identifier. The
voice identifier is returned by the DTK$INITIALIZE routine.
p-index
VMS usage: longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Index to be inserted. The p-index argument is the address of a
signed longword containing the index value. Valid values are in the
range of 1 to 32767. An index of zero is reserved for use by
DIGITAL.
DTK$SET_KEYPAD_MODE
The Turn the Phone Keypad On and Off routine turns recognition of
the telephone keypad on or off.
Format:
DTK$SET_KEYPAD_MODE voice-id ,keypad-mode
Arguments:
voice-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Voice identifier of the DECtalk device. The voice-id argument is
the address of an unsigned longword containing this identifier. The
voice identifier is returned by the DTK$INITIALIZE routine.
keypad-mode
VMS usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
Mode that determines the status of the telephone keypad. The
keypad-mode argument is the address of an unsigned longword
containing this mode. The valid mode specifiers are:
DTK$K_KEYPAD_ON Turns the keypad on.
DTK$K_KEYPAD_OFF Turns the keypad off.
DTK$K_KEYPAD_AUTO Turns the keypad on with autostop.
DTK$SET_LOGGING_MODE
The Set the Logging Mode for the Video Terminal Connected to the
DECtalk Device routine controls the information that is displayed on
the video terminal while the DECtalk device is functioning.
Format:
DTK$SET_LOGGING_MODE voice-id [,new-mode] [,old-mode]
Arguments:
voice-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Voice identifier of the DECtalk device. The voice-id argument is
the address of an unsigned longword containing this identifier. The
voice identifier is returned by the DTK$INITIALIZE routine.
new-mode
VMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
DECtalk mode to be set. The optional new-mode argument is the
address of a longword bit mask containing the specified mode. Valid
values for new-mode are:
o DTK$M_TEXT
o DTK$M_PHONEME
o DTK$M_RAWHOST
o DTK$M_INHOST
o DTK$M_OUTHOST
o DTK$M_ERROR
o DTK$M_TRACE
o DTK$M_DEBUG
old-mode
VMS usage: mask_longword
type: longword (unsigned)
access: write only
mechanism: by reference
Current mode settings of the DECtalk device. The optional old-mode
argument is the address of a longword bit mask that receives the
current DECtalk settings.
DTK$SET_MODE
The Set the Mode for the DECtalk Terminal routine sets or resets the
mode settings of the DECtalk terminal.
Format:
DTK$SET_MODE voice-id [,new-mode] [,old-mode]
Arguments:
voice-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Voice identifier of the DECtalk device. The voice-id argument is
the address of an unsigned longword containing this identifier. The
voice identifier is returned by the DTK$INITIALIZE routine.
new-mode
VMS usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
DECtalk mode to be set. The optional new-mode argument is the
address of a longword bit mask containing the specified mode. Valid
values for new-mode are:
o DTK$M_SQUARE
o DTK$M_ASCII (valid for the DTC01 device only)
o DTK$M_MINUS
o DTK$M_EUROPE (valid for the DTC03 device only)
o DTK$M_SPELL (valid for the DTC03 device only)
old-mode
VMS usage: longword_unsigned
type: longword (unsigned)
access: write only
mechanism: by reference
Current mode settings of the DECtalk device. The optional old-mode
argument is the address of a longword bit mask that receives the
current DECtalk settings.
DTK$SET_SPEECH_MODE
The Turn Speech Mode On and Off routine either starts or stops the
DECtalk device's speech.
Format:
DTK$SET_SPEECH_MODE voice-id ,new-mode [,old-mode]
Arguments:
voice-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Voice identifier of the DECtalk device. The voice-id argument is
the address of an unsigned longword containing this identifier. The
voice identifier is returned by the DTK$INITIALIZE routine.
new-mode
VMS usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
Mode to be set. The new-mode argument is the address of an unsigned
longword containing the specified mode. Valid values are:
DTK$K_SPEAK Start speaking.
DTK$K_STOP Stop speaking when current text is
completed.
DTK$K_HALT Stop speaking immediately.
old-mode
VMS usage: longword_unsigned
type: longword (unsigned)
access: write only
mechanism: by reference
Current speech mode of the DECtalk device. The optional old-mode
argument is the address of an unsigned longword that receives the
current mode setting before enabling the new mode. The values
returned in old-mode are the same as those valid for the new-mode
argument.
DTK$SET_TERMINAL_MODE
The Set the Mode for the Video Terminal Connected to the DECtalk
Device routine controls the attributes of the video terminal
connected to the DECtalk device.
Format:
DTK$SET_TERMINAL_MODE voice-id [,new-mode] [,old-mode]
Arguments:
voice-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Voice identifier of the DECtalk device. The voice-id argument is
the address of an unsigned longword containing this identifier. The
voice identifier is returned by the DTK$INITIALIZE routine.
new-mode
VMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
DECtalk mode to be set. The optional new-mode argument is the
address of a longword bit mask containing the specified mode. Valid
values for new-mode are:
o DTK$M_HOST
o DTK$M_SPEAK
o DTK$M_EDITED
o DTK$M_HARD
o DTK$M_SETUP
o DTK$M_FILTER
old-mode
VMS usage: mask_longword
type: longword (unsigned)
access: write only
mechanism: by reference
Current mode settings of the DECtalk device. The optional old-mode
argument is the address of a longword bit mask that receives the
current DECtalk settings.
DTK$SET_VOICE
The Set Voice Characteristics routine changes the DECtalk voice
characteristics to match those specified.
Format:
DTK$SET_VOICE voice-id [,new-voice] [,speech-rate]
[,comma-pause] [,period-pause]
Arguments:
voice-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Voice identifier of the DECtalk device. The voice-id argument is
the address of an unsigned longword containing this identifier. The
voice identifier is returned by the DTK$INITIALIZE routine.
new-voice
VMS usage: longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Type of voice. The optional new-voice argument is the address of a
signed longword containing any valid new-voice value. Valid values
for new-voice are:
DTK$K_VOICE_MALE Standard male voice
DTK$K_VOICE_FEMALE Standard female voice
DTK$K_VOICE_CHILD Standard child voice
DTK$K_VOICE_DEEP_MALE Deep male voice
DTK$K_VOICE_DEEP_FEMALE Deep female voice
DTK$K_VOICE_OLDER_MALE Older male voice
DTK$K_VOICE_LIGHT_FEMALE Light female voice
speech-rate
VMS usage: longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Rate at which DECtalk speaks, measured in words per minute. The
optional speech-rate argument is the address of a signed longword
containing this rate. The valid range of values for speech-rate is
120 to 350 words per minute.
comma-pause
VMS usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
Number of milliseconds by which to increase the time DECtalk pauses
after a comma. The optional comma-pause argument is the address of
a signed longword containing this number. A value of zero resets
the pause time to the hardware default value.
period-pause
VMS usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
Number of milliseconds by which to increase the time DECtalk pauses
after a period. The optional period-pause argument is the address
of a signed longword containing this number. A value of zero resets
the pause time to the hardware default value.
DTK$SPEAK_FILE
The Speak the Text in a Specified File routine speaks the text
contained in the specified file.
Format:
DTK$SPEAK_FILE voice-id ,filespec [,completion-mode]
Arguments:
voice-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Voice identifier of the DECtalk device. The voice-id argument is
the address of an unsigned longword containing this identifier. The
voice identifier is returned by the DTK$INITIALIZE routine.
filespec
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
File specification of the file containing the text to be spoken.
The filespec argument is the address of a descriptor pointing to
this file.
completion-mode
VMS usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
Mode characteristic. The optional completion-mode argument is the
address of an unsigned longword containing the specified mode.
Valid values for the completion-mode argument are:
DTK$K_IMMED Return to the user immediately (default).
DTK$K_WAIT Wait until the text is completely spoken.
DTK$K_STATUS Wait until the text is completely spoken,
and then return a phone status.
DTK$SPEAK_PHONEMIC_TEXT
The Speak the Specified Phonemic Text routine sends the specified
phonemic text to the DECtalk device to be spoken.
Format:
DTK$SPEAK_PHONEMIC_TEXT voice-id ,text [,completion-mode]
Arguments:
voice-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Voice identifier of the DECtalk device. The voice-id argument is
the address of an unsigned longword containing this identifier. The
voice identifier is returned by the DTK$INITIALIZE routine.
text
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
Phonemic text to be spoken. The text argument is the address of a
descriptor pointing to the specified phonemic representation of the
text.
completion-mode
VMS usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
Mode characteristic. The optional completion-mode argument is the
address of an unsigned longword containing the specified mode.
Valid values for the completion-mode argument are:
DTK$K_IMMED Return to the user immediately (default).
DTK$K_WAIT Wait until the text is completely spoken.
DTK$K_STATUS Wait until the text is completely spoken,
and then return a phone status.
DTK$SPEAK_TEXT
The Speak the Specified Text routine sends the specified text to the
DECtalk device to be spoken.
Format:
DTK$SPEAK_TEXT voice-id ,text [,completion-mode]
Arguments:
voice-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Voice identifier of the DECtalk device. The voice-id argument is
the address of an unsigned longword containing this identifier. The
voice identifier is returned by the DTK$INITIALIZE routine.
text
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
Text to be spoken. The text argument is the address of a descriptor
pointing to the specified text.
completion-mode
VMS usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
Mode characteristic. The optional completion-mode argument is the
address of an unsigned longword containing the specified mode.
Valid values for the completion-mode argument are:
DTK$K_IMMED Return to the user immediately (default).
DTK$K_WAIT Wait until the text is completely spoken.
DTK$K_STATUS Wait until the text is completely spoken,
and then return a phone status.
DTK$SPELL_TEXT
The Spell Text routine causes DECtalk to pronounce each letter of
the specified text.
Format:
DTK$SPELL_TEXT voice-id ,text [,completion-mode]
Arguments:
voice-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Voice identifier of the DECtalk device. The voice-id argument is
the address of an unsigned longword containing this identifier. The
voice identifier is returned by the DTK$INITIALIZE routine.
text
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
Text to be spelled out by DECtalk. The text argument is the address
of a descriptor pointing to the specified string.
completion-mode
VMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
The optional completion mode characteristic. The completion-mode
argument is the address of a longword bit mask containing the
specified mode. Valid values for the completion-mode argument are:
DTK$K_IMMED Return to the user immediately (default).
DTK$K_WAIT Wait until the text is completely spoken.
DTK$K_STATUS Wait until the text is completely spoken,
and then return a phone status.
DTK$TERMINATE
The Terminate DECtalk routine terminates the use of an initialized
DECtalk.
Format:
DTK$TERMINATE voice-id
Arguments:
voice-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Voice identifier of the DECtalk device. The voice-id argument is
the address of an unsigned longword containing this identifier. The
voice identifier is returned by the DTK$INITIALIZE routine.
LIB$
Additional information available:
LIB$ADAWILIB$ADD_TIMESLIB$ADDXLIB$ANALYZE_SDESCLIB$ASN_WTH_MBX
LIB$AST_IN_PROGLIB$ATTACHLIB$BBCCILIB$BBSSILIB$CALLG
LIB$CHARLIB$CONVERT_DATE_STRINGLIB$CRCLIB$CRC_TABLE
LIB$CREATE_DIRLIB$CREATE_USER_VM_ZONELIB$CREATE_VM_ZONE
LIB$CRF_INS_KEYLIB$CRF_INS_REFLIB$CRF_OUTPUTLIB$CURRENCY
LIB$CVT_DX_DXLIB$CVT_FROM_INTERNAL_TIMELIB$CVTF_FROM_INTERNAL_TIME
LIB$CVT_TO_INTERNAL_TIMELIB$CVTF_TO_INTERNAL_TIMELIB$CVT_VECTIM
LIB$DATE_TIMELIB$DAYLIB$DAY_OF_WEEKLIB$DECODE_FAULT
LIB$DEC_OVERLIB$DELETE_FILELIB$DELETE_LOGICALLIB$DELETE_SYMBOL
LIB$DELETE_VM_ZONELIB$DIGIT_SEPLIB$DISABLE_CTRL
LIB$DO_COMMANDLIB$EDIVLIB$EMODDLIB$EMODF
LIB$EMODGLIB$EMODHLIB$EMULLIB$ENABLE_CTRL
LIB$ESTABLISHLIB$EXTVLIB$EXTZVLIB$FID_TO_NAMELIB$FILE_SCAN
LIB$FILE_SCAN_ENDLIB$FIND_FILELIB$FIND_FILE_ENDLIB$FIND_IMAGE_SYMBOL
LIB$FIND_VM_ZONELIB$FIXUP_FLTLIB$FLT_UNDERLIB$FORMAT_DATE_TIME
LIB$FREE_DATE_TIME_CONTEXTLIB$FREE_EFLIB$FREE_LUN
LIB$FREE_TIMERLIB$FREE_VMLIB$FREE_VM_PAGELIB$GETDVI
LIB$GETJPILIB$GETQUILIB$GETSYILIB$GET_COMMAND
LIB$GET_COMMONLIB$GET_DATE_FORMATLIB$GET_EF
LIB$GET_FOREIGNLIB$GET_INPUTLIB$GET_LUNLIB$GET_MAXIMUM_DATE_LENGTH
LIB$GET_SYMBOLLIB$GET_USERS_LANGUAGELIB$GET_VM
LIB$GET_VM_PAGELIB$ICHARLIB$INDEXLIB$INIT_DATE_TIME_CONTEXT
LIB$INIT_TIMERLIB$INSERT_TREELIB$INSQHILIB$INSQTILIB$INSV
LIB$INT_OVERLIB$LENLIB$LOCCLIB$LOOKUP_KEYLIB$LOOKUP_TREE
LIB$LP_LINESLIB$MATCHCLIB$MATCH_CONDLIB$MOVC3
LIB$MOVC5LIB$MOVTCLIB$MOVTUCLIB$MULT_DELTA_TIME
LIB$MULTF_DELTA_TIMELIB$PAUSELIB$POLYDLIB$POLYFLIB$POLYG
LIB$POLYHLIB$PUT_COMMONLIB$PUT_OUTPUTLIB$RADIX_POINT
LIB$REMQHILIB$REMQTILIB$RENAME_FILELIB$RESERVE_EF
LIB$RESET_VM_ZONELIB$REVERTLIB$RUN_PROGRAMLIB$SCANC
LIB$SCOPY_DXDXLIB$SCOPY_R_DXLIB$SET_LOGICALLIB$SET_SYMBOL
LIB$SFREE1_DDLIB$SFREEN_DDLIB$SGET1_DDLIB$SHOW_TIMER
LIB$SHOW_VMLIB$SHOW_VM_ZONELIB$SIGNALLIB$SIG_TO_RET
LIB$SIG_TO_STOPLIB$SIM_TRAPLIB$SKPCLIB$SPANCLIB$SPAWN
LIB$STAT_TIMERLIB$STAT_VMLIB$STOPLIB$SUB_TIMES
LIB$SUBXLIB$SYS_ASCTIMLIB$SYS_FAOLIB$SYS_FAOL
LIB$SYS_GETMSGLIB$TPARSELIB$TRA_ASC_EBCLIB$TRA_EBC_ASC
LIB$TRAVERSE_TREELIB$TRIM_FILESPECLIB$VERIFY_VM_ZONE
LIB$WAIT
LIB$ADAWI
The Add Aligned Word with Interlock routine allows the user to
perform an interlocked add operation using an aligned word.
Format:
LIB$ADAWI add ,sum ,sign
Arguments:
add
VMS usage: word_signed
type: word (signed)
access: read only
mechanism: by reference
The addend operand to be added to the value of sum. The add
argument is the address of a signed word that contains the addend
operand.
sum
VMS usage: word_signed
type: word integer (signed)
access: modify
mechanism: by reference
The word to which add is added. The sum argument is the address of
a signed word integer containing this value.
sign
VMS usage: word_signed
type: word integer (signed)
access: modify
mechanism: by reference
Sign of the sum argument. The sign argument is the address of a
signed word integer that is assigned the value -1, 0, or 1,
depending on whether the new value of sum is negative, 0, or
positive.
LIB$ADD_TIMES
The Add Two Quadword Times routine adds two VMS internal time format
times.
Format:
LIB$ADD_TIMES time1 ,time2 ,resultant-time
Arguments:
time1
VMS usage: date_time
type: quadword (unsigned)
access: read only
mechanism: by reference
First time that LIB$ADD_TIMES adds to the second time. The time1
argument is the address of an unsigned quadword containing the first
time to be added. Time1 may be either a delta time or an absolute
time; however, at least one of the arguments, time1 or time2, must
be a delta time.
time2
VMS usage: date_time
type: quadword (unsigned)
access: read only
mechanism: by reference
Second time that LIB$ADD_TIMES adds to the first time. The time2
argument is the address of an unsigned quadword containing the
second time to be added. Time2 may be either a delta time or an
absolute time; however, at least one of the arguments, time1 or
time2, must be a delta time.
resultant-time
VMS usage: date_time
type: quadword (unsigned)
access: write only
mechanism: by reference
The result of adding time1 and time2. The resultant-time argument
is the address of an unsigned quadword containing the result. If
both time1 and time2 are delta times, then resultant-time is a delta
time. Otherwise, resultant-time is an absolute time.
LIB$ADDX
The Add Two Multiple-Precision Binary Numbers routine adds two
signed two's complement integers of arbitrary length.
Format:
LIB$ADDX addend-array ,augend-array ,resultant-array
[,array-length]
Arguments:
addend-array
VMS usage: vector_longword_signed
type: unspecified
access: read only
mechanism: by reference, array reference
First multiple-precision, signed two's complement integer which
LIB$ADDX adds to the second two's complement integer. The
addend-array argument is the address of the array containing the
two's complement number to be added.
augend-array
VMS usage: vector_longword_signed
type: unspecified
access: read only
mechanism: by reference, array reference
Second multiple-precision, signed two's complement integer, which
LIB$ADDX adds to the first two's complement integer. The
augend-array argument is the address of the array containing the
two's complement number.
resultant-array
VMS usage: vector_longword_signed
type: unspecified
access: write only
mechanism: by reference, array reference
Multiple-precision, signed two's complement integer result of the
addition. The resultant-array argument is the address of the array
into which LIB$ADDX writes the result of the addition.
array-length
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Length in longwords of the arrays to be operated on; each array is
of length len. The len argument is the address of a signed longword
integer containing the length. Len must not be negative. This is
an optional argument. If omitted, the default is 2.
LIB$ANALYZE_SDESC
The Analyze String Descriptors routine extracts the length and the
address at which the data starts for a variety of string descriptor
classes.
Format:
LIB$ANALYZE_SDESC input-descriptor ,data-length ,data-address
Arguments:
input-descriptor
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
Input descriptor from which LIB$ANALYZE_DESC extracts the data's
length and starting address. The input-descriptor argument is the
address of a descriptor pointing to this descriptor.
data-length
VMS usage: word_unsigned
type: word (unsigned)
access: write only
mechanism: by reference
Length of the data; LIB$ANALYSE_DESC extracts this length value from
the input descriptor. The data-length argument is the address of an
unsigned word integer into which LIB$ANALYZE_SDESC writes the
length.
data-address
VMS usage: address
type: longword (unsigned)
access: write only
mechanism: by reference
Starting address of the data; LIB$ANALYZE_DESC extracts this address
from the input descriptor. The data-address argument is the address
of an unsigned longword into which LIB$ANALYZE_DESC writes the
starting address of the data.
LIB$ASN_WTH_MBX
The Assign Channel with Mailbox routine assigns a channel to a
specified device and associates a mailbox with the device. It
returns both the device channel and the mailbox channel.
Format:
LIB$ASN_WTH_MBX device-name ,maximum-message-size
,buffer-quota ,device-channel ,mailbox-channel
Arguments:
device-name
VMS usage: device_name
type: character string
access: read only
mechanism: by descriptor
Device name which LIB$ASN_WTH_MBX passes to the $ASSIGN service.
The device-name argument is the address of a descriptor pointing to
the device name.
maximum-message-size
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Maximum message size that can be sent to the mailbox;
LIB$ASN_WTH_MBX passes this argument to the $CREMBX service. The
maximum-message-size argument is the address of a signed longword
integer containing this maximum message size.
buffer-quota
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Number of system dynamic memory bytes that can be used to buffer
messages sent to the mailbox; LIB$ASN_WTH_MBX passes this argument
to the $CREMBX service. The buffer-quota argument is the address of
a signed longword integer containing this buffer quota.
device-channel
VMS usage: word_unsigned
type: word integer (unsigned)
access: write only
mechanism: by reference
Device channel which LIB$ASN_WTH_MBX receives from the $ASSIGN
service. The device-channel argument is the address of an unsigned
word integer into which $ASSIGN writes the device channel.
mailbox-channel
VMS usage: channel
type: word integer (unsigned)
access: write only
mechanism: by reference
Mailbox channel which LIB$ASN_WTH_MBX receives from the $CREMBX
service. The mailbox-channel argument is the address of an unsigned
word integer into which $CREMBX writes the mailbox channel.
LIB$AST_IN_PROG
The AST in Progress routine indicates whether an AST is currently in
progress.
Format:
LIB$AST_IN_PROG
NONE
LIB$ATTACH
The Attach Terminal to Process routine requests the calling
process's Command Language Interpreter (CLI) to detach the terminal
of the calling process and to reattach it to a different process.
Format:
LIB$ATTACH process-id
Argument
process-id
VMS usage: process_id
type: longword integer (unsigned)
access: read only
mechanism: by reference
Identification of the process to which LIB$ATTACH requests the
calling process to attach its terminal. The process-id argument is
the address of an unsigned longword integer containing the process
identification. The specified process must be currently detached
(by means of a SPAWN or ATTACH command, or by a call to LIB$SPAWN or
LIB$ATTACH) and must be part of the caller's job.
LIB$BBCCI
The Test and Clear Bit with Interlock routine tests and clears a
selected bit under memory interlock. LIB$BBCCI makes the VAX BBCCI
instruction available as a callable procedure.
Format:
LIB$BBCCI position ,bit-zero-address
Arguments:
position
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Bit position, relative to bit-zero-address, of the bit which
LIB$BBCCI tests and clears. The position argument is the address of
a signed longword integer containing the bit position. A position
of zero denotes the low-order bit of the byte base. The bit
position is equal to the offset of the bit chosen from the base
position. This offset may span the entire range of a signed
longword integer; negative offsets access bits in lower-addressed
bytes.
bit-zero-address
VMS usage: address
type: unspecified
access: read only
mechanism: by reference
Address of the byte containing bit zero of the field that LIB$BBCCI
references. The bit-zero-address argument is the address of the
base position. The bit that LIB$BBCCI tests and clears is position
bits offset from the low bit of bit-zero-address.
LIB$BBSSI
The Test and Set Bit with Interlock routine tests and sets a
selected bit under memory interlock. LIB$BBSSI makes the VAX BBSSI
instruction available as a callable procedure.
Format:
LIB$BBSSI position ,bit-zero-address
Arguments:
position
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Bit position, relative to bit-zero-address, of the bit which
LIB$BBSSI tests and sets. The position argument is the address of a
signed longword integer containing the bit position. A position of
zero denotes the low-order bit of the byte base. The bit position
is equal to the offset of the bit chosen from the base position.
This offset may span the entire range of a signed longword integer;
negative offsets access bits in lower-addressed bytes.
bit-zero-address
VMS usage: address
type: unspecified
access: read only
mechanism: by reference
Address of the byte containing bit zero of the field that LIB$BBSSI
references. The bit-zero-address argument is the address of the
base position. The bit that LIB$BBSSI tests and sets is position
bits offset from the low bit of bit-zero-address.
LIB$CALLG
The Call Procedure with General Argument List routine calls a
procedure with an argument list specified as an array of longwords,
the first of which is a count of the remaining longwords. LIB$CALLG
is a callable version of the VAX CALLG instruction.
Format:
LIB$CALLG argument-list ,user-procedure
Arguments:
argument-list
VMS usage: arg_list
type: unspecified
access: read only
mechanism: by reference, array reference
Argument list which LIB$CALLG uses to call the specified procedure.
The argument-list argument is the address of an array of longwords
containing the argument list. The first longword must contain the
count of the remaining longwords. The maximum value of the count is
255.
user-procedure
VMS usage: procedure
type: procedure entry mask
access: function call (before return)
mechanism: by value
Procedure which LIB$CALLG calls with the specified argument list.
The user-procedure argument is the address of the procedure entry
mask for this procedure.
LIB$CHAR
The Transform Byte to First Character of String routine transforms a
single 8-bit ASCII character to an ASCII string consisting of a
single character followed by trailing spaces, if needed, to fill out
the string. The range of the input byte is 0 through 255.
Format:
LIB$CHAR one-character-string ,ascii-code
Arguments:
one-character-string
VMS usage: char_string
type: character string
access: write only
mechanism: by descriptor
ASCII character string consisting of a single character followed by
trailing spaces, if needed, that LIB$CHAR creates when it transforms
the ASCII character code. The one-character-string argument is the
address of a descriptor pointing to the character string that
LIB$CHAR writes.
ascii-code
VMS usage: byte_unsigned
type: byte (unsigned)
access: read only
mechanism: by reference
Single 8-bit ASCII character code that LIB$CHAR transforms to an
ASCII string. The ascii-code argument is the address of an unsigned
byte containing the ASCII character code.
LIB$CONVERT_DATE_STRING
The Convert Date String to Quadword routine converts an absolute
date string into a VMS internal format date-time quadword.
Format:
LIB$CONVERT_DATE_STRING date-string ,date-time [,user-context]
[,flags] [,defaults] [,defaulted-fields]
Arguments:
date-string
VMS usage: time_name
type: character-coded text string
access: read only
mechanism: by descriptor
Date string that specifies the absolute time to be converted to an
internal system time. The date-string argument is the address of a
descriptor pointing to this date string.
date-time
VMS usage: date_time
type: quadword (unsigned)
access: write only
mechanism: by reference
Receives the converted time. The date-time argument is the address
of an unsigned quadword that contains this converted time.
user-context
VMS usage: context
type: longword (unsigned)
access: modify
mechanism: by reference
Context variable that retains the translation context over multiple
calls to this routine. The user-context argument is the address of
an unsigned longword that contains this context. The initial value
of the context variable must be zero. Thereafter, the user program
must not write to the cell.
flags
VMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies which date or time fields might be omitted so that default
values are applied. The flags argument is the address of a
longword bit mask that contains these flags. A set bit indicates
that the field may be omitted. The bit definitions for the mask
correspond to the fields in a $NUMTIM "timbuf" structure as follows:
Field Bit Number Mask
Year 0 1
Month 1 2
Day of month 2 4
Hours 3 8
Minutes 4 16
Seconds 5 32
Fractional seconds 6 64
defaults
VMS usage: vector_word_unsigned
type: word (unsigned)
access: read only
mechanism: by reference
Supplies the defaults to be used for omitted fields. The defaults
argument is the address of an array of unsigned words containing
these default values. This array corresponds to a 7-word $NUMTIM
"timbuf" structure.
defaulted-fields
VMS usage: mask_longword
type: longword (unsigned)
access: write only
mechanism: by reference
Indicates which date or time fields have been defaulted. The
defaulted-fields argument is the address of a longword bit mask that
specifies these fields. The bit definitions are identical to those
of the input-flags bit mask. A set bit indicates the field was
defaulted. Bits 7 through 31, which are reserved for use by
DIGITAL, are zeroed.
LIB$CRC
The Calculate a Cyclic Redundancy Check routine calculates the
cyclic redundancy check (CRC) for a data stream. LIB$CRC makes the
VAX CRC instruction available as a callable procedure.
Format:
LIB$CRC crc-table ,initial-crc ,stream
Arguments:
crc-table
VMS usage: vector_longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference, array reference
The 16-longword cyclic redundancy check table, created by a call to
LIB$CRC_TABLE. The crc-table argument is the address of a signed
longword integer containing this table. Because this table is
created by LIB$CRC_TABLE and then used as input in LIB$CRC, your
program must call LIB$CRC_TABLE before it calls LIB$CRC.
initial-crc
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Initial cyclic redundancy check. The initial-crc argument is the
address of a signed longword integer containing the initial cyclic
redundancy check.
stream
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
Data stream for which LIB$CRC is calculating the CRC. The stream
argument is the address of a descriptor pointing to the data stream.
LIB$CRC_TABLE
The Construct a Cyclic Redundancy Check Table routine constructs a
16-longword table that uses a cyclic redundancy check polynomial
specification as a bit mask.
Format:
LIB$CRC_TABLE polynomial-coefficient ,crc-table
Arguments:
polynomial-coefficient
VMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
A bit mask indicating which polynomial coefficients are to be
generated by LIB$CRC_TABLE. The polynomial-coefficient argument is
the address of an unsigned longword integer containing this bit
mask.
crc-table
VMS usage: vector_longword_signed
type: longword integer (signed)
access: write only
mechanism: by reference, array reference
The 16-longword table that LIB$CRC_TABLE produces. The crc-table
argument is the address of a signed longword integer containing the
table.
LIB$CREATE_DIR
The Create a Directory routine creates a directory or subdirectory.
Format:
LIB$CREATE_DIR device-directory-spec [,owner-UIC]
[,protection-enable] [,protection-value]
[,maximum-versions] [,relative-volume-number]
Arguments:
device-directory-spec
VMS usage: device_name
type: character string
access: read only
mechanism: by descriptor
Directory specification of the directory or subdirectory that
LIB$CREATE_DIR will create. The device-directory-spec argument is
the address of a descriptor pointing to this directory
specification.
owner-UIC
VMS usage: uic
type: longword (unsigned)
access: read only
mechanism: by reference
User Identification Code (UIC) identifying the owner of the created
directory or subdirectory. The owner-UIC argument is the address of
an unsigned longword that contains the UIC. If owner-UIC is zero,
the owner UIC is that of the parent directory.
protection-enable
VMS usage: mask_word
type: word (unsigned)
access: read only
mechanism: by reference
Mask specifying the bits of protection-value to be set. The
protection-enable argument is the address of an unsigned word
containing this protection mask.
protection-value
VMS usage: file_protection
type: word (unsigned)
access: read only
mechanism: by reference
System/Owner/Group/World protection value of the directory you are
creating. The protection-value argument is the address of an
unsigned word which contains this protection mask.
maximum-versions
VMS usage: word_unsigned
type: word (unsigned)
access: read only
mechanism: by reference
Maximum number of versions allowed for files created in the newly
created directories. The maximum-versions argument is the address
of an unsigned word containing the value of the maximum number of
versions.
relative-volume-number
VMS usage: word_unsigned
type: word (unsigned)
access: read only
mechanism: by reference
Relative volume number within a volume set on which the directory or
subdirectory is created. The relative-volume-number argument is the
address of an unsigned word containing the relative volume number.
The relative-volume-number argument is optional. The default is
arbitrary placement within the volume set.
LIB$CREATE_USER_VM_ZONE
The Create User-Defined Storage Zone routine creates a new
user-defined storage zone.
Format:
LIB$CREATE_USER_VM_ZONE zone-id [,user-argument]
[,user-allocation-routine]
[,user-deallocation-routine] [,user-reset-routine]
[,user-delete-routine] [,zone-name]
Arguments:
zone-id
VMS usage: identifier
type: longword (unsigned)
access: write only
mechanism: by reference
Zone identifier. The zone-id argument is the address of a longword
that is set to the identifier of the newly created zone.
user-argument
VMS usage: user_arg
type: longword (unsigned)
access: read only
mechanism: by reference
User argument. The user-argument argument is the address of an
unsigned longword containing the user argument.
LIB$CREATE_USER_VM_ZONE copies the value of user-argument and
supplies the value to all user-routines invoked.
user-allocation-routine
VMS usage: procedure
type: procedure entry mask
access: function call (before return)
mechanism: by value
User allocation routine. The user-allocation-routine argument is
the address of the procedure entry mask for the optional user
routine that is invoked each time LIB$GET_VM is called for the zone.
user-deallocation-routine
VMS usage: procedure
type: procedure entry mask
access: function call (before return)
mechanism: by value
User deallocation routine. The user-deallocation-routine argument
is the address of the procedure entry mask for the optional user
routine that is invoked each time LIB$FREE_VM is called for the
zone.
user-reset-routine
VMS usage: procedure
type: procedure entry mask
access: function call (before return)
mechanism: by value
User routine to reset the zone. The user-reset-routine argument is
an optional user routine that is invoked each time LIB$RESET_VM_ZONE
is called for the zone.
user-delete-routine
VMS usage: procedure
type: procedure entry mask
access: function call (before return)
mechanism: by value
User routine to delete the zone. The user-delete-routine argument
is an optional user routine that is invoked when LIB$DELETE_VM_ZONE
is called for the zone.
zone-name
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
Name to be associated with the zone being created. The optional
zone-name argument is the address of a descriptor pointing to the
zone name. If zone-name is not specified, the zone will not have an
associated name.
LIB$CREATE_VM_ZONE
The Create a New Zone routine creates a new storage zone according
to specified arguments.
Format:
LIB$CREATE_VM_ZONE zone-id [,algorithm] [,algorithm-argument]
[,flags] [,extend-size] [,initial-size] [,block-size]
[,alignment] [,page-limit] [,smallest-block-size]
[,zone-name] [,get-page] [,free-page]
Arguments:
zone-id
VMS usage: identifier
type: longword (unsigned)
access: write only
mechanism: by reference
Zone identifier. The zone-id argument is the address of a longword
that is set to the zone identifier of the newly created zone.
algorithm
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Algorithm. The algorithm argument is the address of a longword
integer that represents the code for one of the LIB$VM algorithms:
1 LIB$K_VM_FIRST_FIT First fit
2 LIB$K_VM_QUICK_FIT Quick fit, lookaside list
3 LIB$K_VM_FREQ_SIZES Frequent sizes, lookaside
list
4 LIB$K_VM_FIXED Fixed size blocks
algorithm-argument
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Algorithm argument. The algorithm-argument argument is the address
of a longword integer that contains a value that is specific to the
particular allocation algorithm.
Algorithm Value
First fit Not used, may be omitted.
Quick fit The number of lookaside lists used. The
number of lists must be between 1 and
128.
Frequent sizes The number of lookaside lists used. The
number of lists must be between 1 and
16.
Fixed size blocks The fixed request size (in bytes) for each
get or free. The request size must be
greater than 0.
flags
VMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Flags. The flags argument is the address of a longword integer
which contains flag bits that control various options:
Bit Value Description
Bit 0 LIB$M_VM_BOUNDARY_TAGS Boundary tags for faster freeing
Adds a minimum of eight bytes to
each block
Bit 1 LIB$M_VM_GET_FILL0 LIB$GET_VM; fill with bytes of 0
Bit 2 LIB$M_VM_GET_FILL1 LIB$GET_VM; fill with bytes of
FF (hexadecimal)
Bit 3 LIB$M_VM_FREE_FILL0 LIB$FREE_VM; fill with bytes of
0
Bit 4 LIB$M_VM_FREE_FILL1 LIB$FREE_VM; fill with bytes of
FF (hexadecimal)
Bit 5 LIB$M_VM_EXTEND_AREA Add extents to existing areas if
possible
extend-size
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Zone extend size. The extend-size argument is the address of a
longword integer which contains the number of (512-byte) pages to be
added to the zone each time it is extended.
initial-size
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Initial size for the zone. The initial-size argument is the address
of a longword integer which contains the number of (512-byte) pages
to be allocated for the zone as the zone is created.
block-size
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Block size of the zone. The block-size argument is the address of a
longword integer specifying the allocation quantum (in bytes) for
the zone. All blocks allocated are rounded up to a multiple of
block-size.
alignment
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Block alignment. The alignment argument is the address of a
longword integer which specifies the required address alignment (in
bytes) for each block allocated.
page-limit
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Maximum page limit. The page-limit argument is the address of a
longword integer which specifies the maximum number of (512-byte)
pages that can be allocated for the zone. The value of page-limit
must be between 0 and 32,767. Note that part of the zone is used
for header information.
smallest-block-size
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Smallest block size. The smallest-block-size argument is the
address of a longword integer which specifies the smallest block
size (in bytes) that has a lookaside list for the quick fit
algorithm.
zone-name
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
Name to be associated with the zone being created. The optional
zone-name argument is the address of a descriptor pointing to the
zone name. If zone-name is not specified, the zone will not have an
associated name.
get-page
VMS usage: procedure
type: procedure entry mask
access: read only
mechanism: by value
Routine that allocates pages of memory. The get-page argument is the
address of a procedure entry mask used to allocate pages of memory.
free-page
VMS usage: procedure
type: procedure entry mask
access: read only
mechanism: by value
Routine that deallocates pages of memory. The free-page argument is
the address of a procedure entry mask used to deallocate pages of
memory.
LIB$CRF_INS_KEY
The Insert Key in Cross-Reference Table routine inserts information
about a key into a cross-reference table.
Format:
LIB$CRF_INS_KEY control-table ,key-string ,symbol-value ,flags
Arguments:
control-table
VMS usage: vector_longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference, array reference
Cross-reference table into which LIB$CRF_INS_KEY inserts information
about the key. The control-table argument is the address of a
signed longword integer pointing to the cross-reference table. You
must name this table each time you call a cross-reference procedure
because you can accumulate information for more than one
cross-reference table at a time.
key-string
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
A counted ASCII string that contains a symbol name or an unsigned
binary longword. The key-string argument is the address of a
descriptor pointing to the key.
symbol-value
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Symbol value, the address of which LIB$CRF_INS_KEY inserts in the
cross-reference table. The symbol-value argument is the address of
a signed longword integer containing this value. Both the key and
value addresses must be permanent addresses in the user's symbol
table.
flags
VMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Value used in selecting the contents of the KEY2 and VAL2 fields;
flags is stored with the entry. The flags argument is the address
of an unsigned longword containing the flags. When preparing the
output line, LIB$CRF_OUTPUT uses flags and the 16-bit mask in the
field descriptor table to extract the data. The high-order bit of
the word is reserved for LIB$CRF_INS_KEY.
LIB$CRF_INS_REF
The Insert Reference to a Key in the Cross-Reference Table routine
inserts a reference to a key in a cross-reference symbol table.
Format:
LIB$CRF_INS_REF control-table ,longword-integer-key
,reference-string ,longword-integer-reference
,ref-definition-indicator
Arguments:
control-table
VMS usage: vector_longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference, array reference
Control table associated with this cross-reference. The
control-table argument is the address of an array containing the
control table.
longword-integer-key
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Key referred to by LIB$CRF_INS_REF. The longword-integer-key
argument is the address of a signed longword integer containing the
key. The key is a counted ASCII string that contains a symbol name
or an unsigned binary longword. It must be a permanent address in
the user's symbol table.
reference-string
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
Counted ASCII string with a maximum of 31 characters, not including
the byte count. The reference-string argument is the address of a
descriptor pointing to the counted ASCII string.
longword-integer-reference
VMS usage: longword_signed
type: longword integer (signed)
access: write only
mechanism: by reference
The 16-bit value used in selecting the contents of the REF1 field.
The longword-integer-reference argument is the address of a signed
longword integer containing this value. When preparing the output
line, LIB$CRF_OUTPUT uses longword-integer-reference and the bit
mask in the field descriptor table to extract the data. The
high-order bit of the word is reserved for LIB$CRF_INS_REF.
ref-definition-indicator
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Reference/definition indicator that LIB$CRF_INS_REF uses to
distinguish between a reference to a symbol and the definition of
the symbol. The ref-definition-indicator argument is the address of
a signed longword integer containing this indicator. The only
difference between processing a symbol reference and a symbol
definition is where LIB$CRF_INS_REF stores the information.
LIB$CRF_OUTPUT
The Output Cross-Reference Table Information routine extracts the
information from the cross-reference tables and formats the output
pages.
Format:
LIB$CRF_OUTPUT control-table ,output-line-width ,page1
,page2 ,mode-indicator ,delete-save-indicator
Arguments:
control-table
VMS usage: vector_longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference, array reference
Control table associated with the cross-reference. The
control-table argument is the address of an array containing the
control table. The table contains the address of the user-supplied
routine that prints the lines formatted by LIB$CRF_OUTPUT.
output-line-width
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Width of the output line. The output-line-width argument is the
address of a signed longword integer containing the width.
page1
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Number of lines on the first page of the output. The page1 argument
is the address of a signed longword integer containing this number.
This allows the user to reserve space to print header information on
the first page of the cross-reference.
page2
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Number of lines per page for the other pages. The page2 argument is
the address of a signed longword integer containing this number.
mode-indicator
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Output mode indicator. The mode-indicator is the address of a
signed longword integer containing the mode indicator.
delete-save-indicator
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Delete/save indicator which LIB$CRF_OUTPUT uses to determine whether
the table's built-in accumulating symbol information is to be saved
or deleted once the cross-reference is produced. The
delete-save-indicator is the address of a signed longword integer
containing the delete/save indicator.
LIB$CURRENCY
The Get System Currency Symbol routine returns the system's currency
symbol.
Format:
LIB$CURRENCY currency-string [,resultant-length]
Arguments:
currency-string
VMS usage: char_string
type: character string
access: write only
mechanism: by descriptor
Currency symbol. The currency-string argument is the address of a
descriptor pointing to the currency symbol.
resultant-length
VMS usage: word_unsigned
type: word (unsigned)
access: write only
mechanism: by reference
Number of characters that LIB$CURRENCY has written into
currency-string, not counting padding in the case of a fixed-length
string. The resultant-length argument is the address of an unsigned
word containing the length of the currency symbol. If the input
string is truncated to the size specified in the currency-string
descriptor, resultant-length is set to this size. Therefore,
resultant-length can always be used by the calling program to access
a valid substring of currency-string.
LIB$CVT_DX_DX
The General Data Type Conversion routine converts a VAX standard
atomic or string datum described by a source descriptor to another
VAX standard atomic or string datum described by a destination
descriptor. This conversion is supported over a subset of the VAX
standard data types.
Format:
LIB$CVT_DX_DX source-item ,destination-item
[,word-integer-dest-length]
Arguments:
source-item
VMS usage: unspecified
type: unspecified
access: read only
mechanism: by descriptor
Source item to be converted by LIBCVT_DX_DX. The source-item
argument is the address of a descriptor pointing to the source item
to be converted. The type of the item to be converted is contained
in the descriptor.
destination-item
VMS usage: unspecified
type: unspecified
access: write only
mechanism: by descriptor
Destination of the conversion. The destination-item argument is the
address of a descriptor pointing to the destination item. The
destination descriptor specifies the data type to which the source
item is converted.
word-integer-dest-length
VMS usage: word_unsigned
type: word (unsigned)
access: write only
mechanism: by reference
Length in bytes of the destination item (when that item is a string)
that has been converted by LIB$CVT_DX_DX, not including any space
filling. The word-integer-dest-length argument contains the address
of an unsigned word containing this length.
LIB$CVT_FROM_INTERNAL_TIME
The Convert Internal Time to External Time routine converts an
internal VMS system time (either absolute or delta) into an external
longword time.
Format:
LIB$CVT_FROM_INTERNAL_TIME operation ,resultant-time
[,input-time]
Arguments:
operation
VMS usage: function_code
type: longword (unsigned)
access: read only
mechanism: by reference
The conversion to be performed. The operation argument is the
address of an unsigned longword containing the operation.
resultant-time
VMS usage: longword_unsigned
type: longword (unsigned)
access: write only
mechanism: by reference
The external time that results from the conversion. The
resultant-time argument is the address of an unsigned longword
containing the result.
input-time
VMS usage: date_time
type: quadword (unsigned)
access: read only
mechanism: by reference
Optional absolute or delta time to be converted. The input-time
argument is the address of an unsigned quadword containing the time.
If you do not supply a value for input-time, the current system time
is used.
LIB$CVTF_FROM_INTERNAL_TIME
The Convert Internal Time to External Time routine (F-floating point
value) converts a delta internal VMS system time into an external
F-floating time.
Format:
LIB$CVTF_FROM_INTERNAL_TIME operation ,resultant-time
,input-time
Arguments:
operation
VMS usage: function_code
type: longword (unsigned)
access: read only
mechanism: by reference
The conversion to be performed. The operation argument is the
address of an unsigned longword containing the operation. Valid
values for operation are the following:
Operation Interpretation
LIB$K_DELTA_WEEKS_F Fractional weeks
LIB$K_DELTA_DAYS_F Fractional days
LIB$K_DELTA_HOURS_F Fractional hours
LIB$K_DELTA_MINUTES_F Fractional minutes
LIB$K_DELTA_SECONDS_F Fractional seconds
resultant-time
VMS usage: floating_point
type: F-floating
access: write only
mechanism: by reference
The external time that results from the conversion. The
resultant-time argument is the address of an F-floating point value
containing the result.
input-time
VMS usage: date_time
type: quadword (unsigned)
access: read only
mechanism: by reference
Delta time to be converted. The input-time argument is the address
of an unsigned quadword containing the time.
LIB$CVT_TO_INTERNAL_TIME
The Convert External Time to Internal Time routine converts an
external time interval into a VMS internal format delta time.
Format:
LIB$CVT_TO_INTERNAL_TIME operation ,input-time
,resultant-time
Arguments:
operation
VMS usage: function_code
type: longword (unsigned)
access: read only
mechanism: by reference
The conversion to be performed. The operation argument is the
address of an unsigned longword containing the operation. Valid
values for operation are the following:
Operation Interpretation
LIB$K_DELTA_WEEKS Whole weeks in delta time
LIB$K_DELTA_DAYS Whole days in delta time
LIB$K_DELTA_HOURS Whole hours in delta time
LIB$K_DELTA_MINUTES Whole minutes in delta time
LIB$K_DELTA_SECONDS Whole seconds in delta time
input-time
VMS usage: varying_arg
type: longword (unsigned)
access: read only
mechanism: by reference
Time to be converted. The input-time argument is the address of
this input time. The value you supply for input-time must not be
negative nor equivalent to greater than 10,000 days.
resultant-time
VMS usage: date_time
type: quadword (unsigned)
access: write only
mechanism: by reference
The VMS internal format delta time that results from the conversion.
The resultant-time argument is the address of an unsigned quadword
containing the result.
LIB$CVTF_TO_INTERNAL_TIME
The Convert External Time to Internal Time routine (F-floating point
value) converts an external time interval into a VMS internal format
F-floating delta time.
Format:
LIB$CVTF_TO_INTERNAL_TIME operation ,input-time
,resultant-time
Arguments:
operation
VMS usage: function_code
type: longword (unsigned)
access: read only
mechanism: by reference
The conversion to be performed. The operation argument is the
address of an unsigned longword containing the operation. Valid
values for operation are the following:
Operation Interpretation
LIB$K_DELTA_WEEKS_F Fractional weeks
LIB$K_DELTA_DAYS_F Fractional days
LIB$K_DELTA_HOURS_F Fractional hours
LIB$K_DELTA_MINUTES_F Fractional minutes
LIB$K_DELTA_SECONDS_F Fractional seconds
input-time
VMS usage: varying_arg
type: F-floating
access: read only
mechanism: by reference
Delta time to be converted. The input-time argument is the address
of this input time. The value you supply for input-time must not be
negative nor equivalent to greater than 10,000 days.
resultant-time
VMS usage: date_time
type: quadword (unsigned)
access: write only
mechanism: by reference
The VMS internal format delta time that results from the conversion.
The resultant-time argument is the address of an unsigned quadword
containing the result.
LIB$CVT xTB
The Convert Numeric Text to Binary routines return a binary
representation of the ASCII text string representation of a decimal,
hexadecimal, or octal number.
Format:
LIB$CVT_DTB byte-count ,numeric-string ,result
LIB$CVT_HTB byte-count ,numeric-string ,result
LIB$CVT_OTB byte-count ,numeric-string ,result
Arguments:
byte-count
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by value
Byte count of the input ASCII text string. The byte-count argument
is a signed longword integer containing the byte count of the input
string.
numeric-string
VMS usage: char_string
type: character string
access: read only
mechanism: by reference
ASCII text string representation of a decimal, hexadecimal, or octal
number which LIB$CVTxTB converts to binary representation. The
numeric-string argument is the address of a character string
containing this input string to be converted.
result
VMS usage: longword_signed
type: longword integer (signed)
access: write only
mechanism: by reference
Binary representation of the input string. The result argument is
the address of a signed longword integer containing the converted
string.
LIB$CVT_VECTIM
The Convert Seven-Word Vector to Internal Time routine converts a
seven-word vector into a VMS internal format delta or absolute time.
Format:
LIB$CVT_VECTIM input-time
,resultant-time
Arguments:
input-time
VMS usage: vector_word_unsigned
type: word (unsigned)
access: read only
mechanism: by reference
Time to be converted. The input-time argument is the address of a
seven-word structure containing this time. The following diagram
depicts the fields in this structure.
31 15 0
__________________________________________________________________
| month of year | year since 0 |
|________________________________|_______________________________|
| hour of day | day of month |
|________________________________|_______________________________|
| second of minute | minute of hour |
|________________________________|_______________________________|
| hundredths of second |
|_______________________________|
resultant-time
VMS usage: date_time
type: quadword (unsigned)
access: write only
mechanism: by reference
The VMS internal format delta or absolute time that results from the
conversion. The resultant-time argument is the address of an
unsigned quadword containing the result.
LIB$DATE_TIME
The Date and Time Returned as a String routine returns the VMS
system date and time in the semantics of a user-provided string.
Format:
LIB$DATE_TIME date-time-string
Argument
date-time-string
VMS usage: time_name
type: character string
access: write only
mechanism: by descriptor
Destination string into which LIB$DATE_TIME writes the system date
and time. The date-time-string argument is the address of a
descriptor pointing to the destination string.
LIB$DAY
The Day Number Returned as a Longword Integer routine returns the
number of days since the system zero date of November 17, 1858, or
the number of days from November 17, 1858, to a user-supplied date.
Format:
LIB$DAY number-of-days [,user-time] [,day-time]
Arguments:
number-of-days
VMS usage: longword_signed
type: longword integer (signed)
access: write only
mechanism: by reference
Number of days since the system zero date. The number-of-days
argument is the address of a signed longword integer containing the
day number.
user-time
VMS usage: date_time
type: quadword (unsigned)
access: read only
mechanism: by reference
User-supplied time, in 100-nanosecond units. The user-time argument
is the address of a signed quadword integer containing the user
time. A positive value indicates an absolute time, while a negative
value indicates a delta time. This is an optional argument. If
omitted, the default is the current system time. This quadword time
value is obtained by calling the system service SYS$BINTIM.
day-time
VMS usage: longword_signed
type: longword integer (signed)
access: write only
mechanism: by reference
Number of 10-millisecond units since midnight of the user-time
argument. The day-time argument is the address of a signed longword
integer into which LIB$DAY writes this number of units.
LIB$DAY_OF_WEEK
The Show Numeric Day of Week routine returns the numeric day of the
week for an input time value. If 0 is the input time value, the
current day of the week is returned. The days are numbered 1
through 7, with Monday as day 1 and Sunday as day 7.
Format:
LIB$DAY_OF_WEEK user-time ,day-number
Arguments:
user-time
VMS usage: date_time
type: quadword (unsigned)
access: read only
mechanism: by reference
Time to be translated to a day of the week, or zero. The user-time
argument is the address of an unsigned quadword containing the value
of time. Time must be supplied as an absolute system time. To
obtain this time value in proper quadword format call the system
service SYS$BINTIM.
day-number
VMS usage: longword_unsigned
type: longword (unsigned)
access: write only
mechanism: by reference
Numeric day of week. The day-number argument is the address of a
longword into which LIB$DAY_OF_WEEK writes the integer value
representing the day of the week.
LIB$DECODE_FAULT
The Decode Instruction Stream During Fault routine is a tool for
building condition handlers which process instruction fault
exceptions. It is called from a condition handler.
Format:
LIB$DECODE_FAULT signal-arguments ,mechanism-arguments
,user-routine [,unspecified-user-argument]
[,instruction-definitions]
Arguments:
signal-arguments
VMS usage: vector_longword_unsigned
type: unspecified
access: read only
mechanism: by reference, array reference
Signal arguments array that was passed from VMS to your condition
handler. The signal-arguments argument is the address of the signal
arguments array.
mechanism-arguments
VMS usage: vector_longword_unsigned
type: unspecified
access: read only
mechanism: by reference, array reference
Mechanism arguments array that was passed from VMS to your condition
handler. The mechanism-arguments argument is the address of the
mechanism arguments array.
user-routine
VMS usage: procedure
type: bound procedure value or procedure entry mask
access: call after stack unwind
mechanism: by descriptor, procedure descriptor
User-supplied action routine that LIB$DECODE_FAULT calls to handle
the exception. The user-routine argument is the address of a
descriptor pointing to your user action routine. user-routine may
be of type "bound procedure value" when called by languages with
up-level addressing. If user-routine is not of type "bound
procedure value," it is assumed to be the address of an entry mask.
unspecified-user-argument
VMS usage: user_arg
type: unspecified
access: read only
mechanism: unspecified
Additional information passed from your handler without
interpretation to your user action routine. The
unspecified-user-argument argument contains the value of this
additional information. This is an optional argument; if omitted,
zero is used.
instruction-definitions
VMS usage: vector_byte_unsigned
type: byte (unsigned)
access: read only
mechanism: by reference, array reference
Array of bytes specifying instruction opcodes and operand
definitions which are to replace or supplement the standard
instruction definitions. The instruction-definitions argument is
the address of this array.
LIB$DEC_OVER
The Enable or Disable Decimal Overflow Detection routine enables or
disables decimal overflow detection for the calling procedure
activation. The previous decimal overflow setting is returned.
Format:
LIB$DEC_OVER new-setting
ARGUMENT
new-setting
VMS usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
New decimal overflow enable setting. The new-setting argument is
the address of an unsigned longword that contains the new decimal
overflow enable setting. Bit 0 set to 1 means enable; bit 0 set to
0 means disable.
LIB$DELETE_FILE
The Delete One or More Files routine deletes one or more files. The
specification of the file(s) to be deleted may include wildcards.
LIB$DELETE_FILE is similar in function to the DCL command DELETE.
Format:
LIB$DELETE_FILE filespec [,default-filespec]
[,related-filespec] [,user-success-routine]
[,user-error-routine] [,user-confirm-routine]
[,user-specified-argument] [,resultant-name]
[,file-scan-context]
Arguments:
filespec
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
String containing the Record Management Services (RMS) file
specification of the file(s) to be deleted. The filespec argument
is the address of a descriptor pointing to the file specification.
If the specification includes wildcards, each file that matches the
specification is deleted. The string must not contain more than 255
characters. Any string class is supported.
default-filespec
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
Default file specification of the file(s) to be deleted. The
default-filespec argument is the address of a descriptor pointing to
the default file specification. This is an optional argument; if
omitted, the default is the null string. Any string class is
supported.
related-filespec
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
Related file specification of the file(s) to be deleted. The
related-filespec argument is the address of a descriptor pointing to
the related file specification. Any string class is supported.
This is an optional argument; if omitted, the default is the null
string.
user-success-routine
VMS usage: procedure
type: procedure entry mask
access: function call (before return)
mechanism: by value
User-supplied success routine that LIB$DELETE_FILE calls after it
successfully deletes a file. The user-success-routine argument is
the address of the entry mask of the success routine.
user-error-routine
VMS usage: procedure
type: procedure entry mask
access: function call (before return)
mechanism: by value
User-supplied error routine that LIB$DELETE_FILE calls when it
detects an error. The user-error-routine argument is the address of
the entry mask of this routine.
user-confirm-routine
VMS usage: procedure
type: procedure entry mask
access: function call (before return)
mechanism: by value
User-supplied confirm routine that LIB$DELETE_FILE calls before each
file is deleted. The user-confirm-routine argument is the address
of the entry mask of this routine. The value returned by the
confirm routine determines whether or not the file will be deleted.
The confirm routine can be used to select specific files for
deletion based on criteria such as expiration date, size, and so on.
user-specified-argument
VMS usage: user_arg
type: unspecified
access: read only
mechanism: unspecified
User-supplied argument that LIB$DELETE_FILE passes to the error,
success and confirm routines each time they are called. Whatever
mechanism is also used to pass user-specified-argument to
LIB$DELETE_FILE is used to pass it to the routines. This is an
optional argument; if omitted, zero is passed by value.
resultant-name
VMS usage: char_string
type: character string
access: write only
mechanism: by descriptor
String into which LIB$DELETE_FILE writes the RMS resultant file
specification of the last file processed. The resultant-name
argument is the address of a descriptor pointing to the resultant
name.
file-scan-context
VMS usage: context
type: longword (unsigned)
access: modify
mechanism: by reference
Context for deleting a list of filespecs. The file-scan-context
argument is the address of a longword containing the context value.
LIB$DELETE_LOGICAL
The Delete Logical Name routine requests the calling process's
Command Language Interpreter (CLI) to delete a supervisor-mode
process logical name. LIB$DELETE_LOGICAL provides the same function
as the DCL command DEASSIGN.
Format:
LIB$DELETE_LOGICAL logical-name [,table-name]
Arguments:
logical-name
VMS usage: logical_name
type: character string
access: read only
mechanism: by descriptor
Logical name to be deleted. The logical-name argument is the
address of a descriptor pointing to this logical name string. The
maximum length of a logical name is 255 characters.
table-name
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
Name of the table from which the logical name is to be deleted. The
table-name argument is the address of a descriptor pointing to this
name string. This is an optional argument. If omitted, the
LNM$PROCESS table is used.
LIB$DELETE_SYMBOL
The Delete CLI Symbol routine requests the calling process's Command
Language Interpreter (CLI) to delete an existing CLI symbol.
Format:
LIB$DELETE_SYMBOL symbol [,table-type-indicator]
Arguments:
symbol
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
Name of the symbol to be deleted by LIB$DELETE_SYMBOL. The symbol
argument is the address of a descriptor pointing to this symbol
string. The symbol name is converted to uppercase and trailing
blanks are removed before use.
table-type-indicator
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Indicator of the table which contains the symbol to be deleted. The
table-type-indicator argument is the address of a signed longword
integer that is this table indicator.
LIB$DELETE_VM_ZONE
The Delete Virtual Memory Zone routine deletes a zone and returns
all pages owned by the zone to the processwide page pool.
Format:
LIB$DELETE_VM_ZONE zone-id
Arguments:
zone-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Zone identifier. The zone-id is the address of a longword that
contains the identifier of a zone created by a previous call to
LIB$CREATE_VM_ZONE or LIB$CREATE_USER_VM_ZONE.
LIB$DIGIT_SEP
The Get Digit Separator Symbol routine returns the system's digit
separator symbol.
Format:
LIB$DIGIT_SEP digit-separator-string [,resultant-length]
Arguments:
digit-separator-string
VMS usage: char_string
type: character string
access: write only
mechanism: by descriptor
Digit separator symbol returned by LIB$DIGIT_SEP. The
digit-separator-string argument is the address of a descriptor
pointing to the digit separator.
resultant-length
VMS usage: word_unsigned
type: word (unsigned)
access: write only
mechanism: by reference
Number of characters written into digit-separator-string, not
counting padding in the case of a fixed-length string. The
resultant-length argument is the address of an unsigned word
containing the length of the digit separator symbol. If the input
string is truncated to the size specified in the
digit-separator-string descriptor, resultant-length is set to this
size. Therefore, resultant-length can always be used by the calling
program to access a valid substring of digit-separator-string.
LIB$DISABLE_CTRL
The Disable CLI Interception of Control Characters routine requests
the calling process's Command Language Interpreter (CLI) to not
intercept the selected control characters when they are typed during
an interactive terminal session. LIB$DISABLE_CTRL provides the same
function as the DCL command SET NOCONTROL.
Format:
LIB$DISABLE_CTRL disable-mask [,old-mask]
Arguments:
disable-mask
VMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Bit mask indicating which control characters are not to be
intercepted. The disable-mask argument is the address of an
unsigned longword containing this bit mask.
old-mask
VMS usage: mask_longword
type: longword (unsigned)
access: write only
mechanism: by reference
Previous bit mask. The old-mask argument is the address of an
unsigned longword into which LIB$DISABLE_CTRL writes the old bit
mask. The old bit mask is of the same form as disable-mask.
LIB$DO_COMMAND
The Execute Command routine stops program execution and directs the
Command Language Interpreter to execute a command which you supply
as the argument. If successful, LIB$DO_COMMAND does not return
control to the calling program. Instead, LIB$DO_COMMAND begins
execution of the specified command.
If you want control to return to the caller, use LIB$SPAWN instead.
Format:
LIB$DO_COMMAND command-string
Argument
command-string
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
Text of the command which LIB$DO_COMMAND executes. The
command-string argument is the address of a descriptor pointing to
the command text. The maximum length of the command is 255
characters.
LIB$EDIV
The Extended-Precision Divide routine performs extended-precision
division. LIB$EDIV makes the VAX EDIV instruction available as a
callable procedure.
Format:
LIB$EDIV longword-integer-divisor ,quadword-integer-dividend
,longword-integer-quotient ,remainder
Arguments:
longword-integer-divisor
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Divisor. The longword-integer-divisor argument is the address of a
signed longword integer containing the divisor.
quadword-integer-dividend
VMS usage: quadword_signed
type: quadword integer (signed)
access: read only
mechanism: by reference
Dividend. The quadword-integer-dividend argument is the address of
a signed quadword integer containing the dividend.
longword-integer-quotient
VMS usage: longword_signed
type: longword integer (signed)
access: write only
mechanism: by reference
Quotient. The longword-integer-quotient argument is the address of
a signed longword integer containing the quotient.
remainder
VMS usage: longword_signed
type: longword integer (signed)
access: write only
mechanism: by reference
Remainder. The remainder argument is the address of a signed
longword integer containing the remainder.
LIB$EMODD
The Extended Multiply and Integerize routine (D-floating point
values) allows higher-level language users to perform accurate range
reduction of D-floating arguments.
Format:
LIB$EMODD floating-point-multiplier ,multiplier-extension
,floating-point-multiplicand ,integer-portion
,fractional-portion
Arguments:
floating-point-multiplier
VMS usage: floating_point
type: D_floating
access: read only
mechanism: by reference
Multiplier. The floating-point-multiplier argument is a D_floating
number.
multiplier-extension
VMS usage: byte_unsigned
type: byte (unsigned)
access: read only
mechanism: by reference
The left-justified multiplier-extension bits. The
multiplier-extension argument is an unsigned byte.
floating-point-multiplicand
VMS usage: floating_point
type: D_floating
access: read only
mechanism: by reference
Multiplicand. The floating-point-multiplicand argument is a
D_floating number.
integer-portion
VMS usage: longword_signed
type: longword integer (signed)
access: write only
mechanism: by reference
Integer portion of the result. The integer-portion argument is the
address of a signed longword integer containing the integer portion
of the result.
fractional-portion
VMS usage: floating_point
type: D_floating
access: write only
mechanism: by reference
Fractional portion of the result. The fractional-portion argument
is a D_floating number.
LIB$EMODF
The Extended Multiply and Integerize routine (F-floating point
values) allows higher-level language users to perform accurate range
reduction of F-floating arguments.
Format:
LIB$EMODF floating-point-multiplier ,multiplier-extension
,floating-point-multiplicand ,integer-portion
,fractional-portion
Arguments:
floating-point-multiplier
VMS usage: floating_point
type: F_floating
access: read only
mechanism: by reference
Multiplier. The floating-point-multiplier argument is the address
of an F_floating number containing the number.
multiplier-extension
VMS usage: byte_unsigned
type: byte (unsigned)
access: read only
mechanism: by reference
The left-justified multiplier-extension bits. The
multiplier-extension argument is the address of an unsigned byte
containing these multiplier extension bits.
floating-point-multiplicand
VMS usage: floating_point
type: F_floating
access: read only
mechanism: by reference
Multiplicand. The floating-point-multiplicand argument is an
F_floating number.
integer-portion
VMS usage: longword_signed
type: longword (signed)
access: write only
mechanism: by reference
Integer portion of the result. The integer-portion argument is the
address of a signed longword integer containing the integer portion
of the result.
fractional-portion
VMS usage: floating_point
type: F_floating
access: write only
mechanism: by reference
Fractional portion of the result. The fractional-portion argument
is the address of an F_floating number containing the fractional
portion of the result.
LIB$EMODG
The Extended Multiply and Integerize routine (G-floating point
values) allows higher-level language users to perform accurate range
reduction of G-floating arguments.
Format:
LIB$EMODG floating-point-multiplier ,multiplier-extension
,floating-point-multiplicand ,integer-portion
,fractional-portion
Arguments:
floating-point-multiplier
VMS usage: floating_point
type: G_floating
access: read only
mechanism: by reference
Multiplier. The floating-point-multiplier argument is a G_floating
number.
multiplier-extension
VMS usage: word_unsigned
type: word (unsigned)
access: read only
mechanism: by reference
The left-justified multiplier-extension bits. The
multiplier-extension argument is an unsigned word.
floating-point-multiplicand
VMS usage: floating_point
type: G_floating
access: read only
mechanism: by reference
Multiplicand. The floating-point-multiplicand argument is a
G_floating number.
integer-portion
VMS usage: longword_signed
type: longword integer (signed)
access: write only
mechanism: by reference
Integer portion of the result. The integer-portion argument is the
address of a signed longword integer containing the integer portion
of the result.
fractional-portion
VMS usage: floating_point
type: G_floating
access: write only
mechanism: by reference
Fractional portion of the result. The fractional-portion argument
is a G_floating number.
LIB$EMODH
The Extended Multiply and Integerize routine (H-floating point
values) allows higher-level language users to perform accurate range
reduction of H-floating arguments.
Format:
LIB$EMODH floating-point-multiplier ,multiplier-extension
,floating-point-multiplicand ,integer-portion
,fractional-portion
Arguments:
floating-point-multiplier
VMS usage: floating_point
type: H_floating
access: read only
mechanism: by reference
Multiplier. The floating-point-multiplier argument is an H_floating
number.
multiplier-extension
VMS usage: word_unsigned
type: word (unsigned)
access: read only
mechanism: by reference
The left-justified multiplier-extension bits. The
multiplier-extension argument is an unsigned word.
floating-point-multiplicand
VMS usage: floating_point
type: H_floating
access: read only
mechanism: by reference
Multiplicand. The floating-point-multiplicand argument is an
H_floating number.
integer-portion
VMS usage: longword_signed
type: longword integer (signed)
access: write only
mechanism: by reference
Integer portion of the result. The integer-portion argument is the
address of a signed longword integer containing the integer portion
of the result.
fractional-portion
VMS usage: floating_point
type: H_floating
access: write only
mechanism: by reference
Fractional portion of the result. The fractional-portion argument
is an H_floating number.
LIB$EMUL
The Extended-Precision Multiply routine performs extended-precision
multiplication. LIB$EMUL makes the VAX EMUL instruction available
as a callable procedure.
Format:
LIB$EMUL longword-integer-multiplier
,longword-integer-multiplicand ,addend ,product
Arguments:
longword-integer-multiplier
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Multiplier used by LIB$EMUL in the extended-precision
multiplication. The longword-integer-multiplier argument is the
address of a signed longword integer containing the multiplier.
longword-integer-multiplicand
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Multiplicand used by LIB$EMUL in the extended-precision
multiplication. The longword-integer-multiplicand argument is the
address of a signed longword integer containing the multiplicand.
addend
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Addend used by LIB$EMUL in the extended-precision multiplication.
The addend argument is the address of a signed longword integer
containing the addend.
product
VMS usage: quadword_signed
type: quadword integer (signed)
access: write only
mechanism: by reference
Product of the extended-precision multiplication. The product
argument is the address of a signed quadword integer into which
LIB$EMUL writes the product.
LIB$ENABLE_CTRL
The Enable CLI Interception of Control Characters routine requests
the calling process's Command Language Interpreter (CLI) to resume
interception of the selected control characters when they are typed
during an interactive terminal session. LIB$ENABLE_CTRL provides
the same function as the DCL command SET CONTROL.
Format:
LIB$ENABLE_CTRL enable-mask [,old-mask]
Arguments:
enable-mask
VMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Bit mask indicating for which control characters LIB$ENABLE_CTRL is
to enable interception. The enable-mask argument is the address of
an unsigned longword containing this bit mask. Each of the 32 bits
corresponds to one of the 32 possible control characters. If a bit
is set, the corresponding control character is intercepted by the
CLI. Currently, only bits 20 and 25, corresponding to CTRL/T and
CTRL/Y, are recognized.
old-mask
VMS usage: mask_longword
type: longword (unsigned)
access: write only
mechanism: by reference
Previous bit mask. The old-mask argument is the address of an
unsigned longword containing the old bit mask. The old bit mask is
of the same form as enable-mask.
LIB$ESTABLISH
The Establish a Condition Handler routine moves the address of a
condition handling routine (which can be a user-written or a library
procedure) to longword 0 of the stack frame of the caller of
LIB$ESTABLISH.
Format:
LIB$ESTABLISH new-handler
Argument
new-handler
VMS usage: procedure
type: procedure entry mask
access: read only
mechanism: by value
Routine to be set up as the condition handler. The new-handler
argument is the address of the procedure entry mask to this routine.
LIB$EXTV
The Extract a Field and Sign-Extend routine returns a sign-extended
longword field that has been extracted from the specified variable
bit field. LIB$EXTV makes the VAX EXTV instruction available as a
callable procedure.
Format:
LIB$EXTV position ,size ,base-address
Arguments:
position
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Position (relative to the base address) of the first bit in the
field that LIB$EXTV extracts. The position argument is the address
of a signed longword integer containing the position.
size
VMS usage: byte_unsigned
type: byte (unsigned)
access: read only
mechanism: by reference
Size of the bit field LIB$EXTV extracts. The size argument is the
address of an unsigned byte containing the size. The maximum size
is 32 bits.
base-address
VMS usage: address
type: longword (unsigned)
access: read only
mechanism: by value
Base address of the bit field LIB$EXTV extracts from the specified
variable bit field. The base-address argument is an unsigned
longword that contains this base address.
LIB$EXTZV
The Extract a Zero-Extended Field routine returns a longword
zero-extended field that has been extracted from the specified
variable bit field. LIB$EXTZV makes the VAX EXTZV instruction
available as a callable procedure.
Format:
LIB$EXTZV position ,size ,base-address
Arguments:
position
VMS usage: longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Position (relative to the base address) of the first bit in the
field LIB$EXTZV extracts. The position argument is the address of a
signed longword integer containing the position.
size
VMS usage: byte_unsigned
type: byte (unsigned)
access: read only
mechanism: by reference
Size of the bit field LIB$EXTZV extracts. The size argument is the
address of an unsigned byte containing the size. The maximum size
is 32 bits.
base-address
VMS usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by value
Base address of the bit field LIB$EXTZV extracts. The base-address
argument is an unsigned longword that contains this base address.
LIB$FFx
The Find First Clear or Set Bit routines search the field specified
by the start position, size, and base for the first clear or set
bit. LIB$FFC and LIB$FFS make the VAX FFC and FFS instructions
available as callable procedures.
Format:
LIB$FFC position ,size ,base ,find-position
LIB$FFS position ,size ,base ,find-position
Arguments:
position
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Starting position, relative to the base address, of the bit field to
be searched by LIB$FFx. The position argument is the address of a
signed longword integer containing the starting position.
size
VMS usage: byte_unsigned
type: byte (unsigned)
access: read only
mechanism: by reference
Number of bits to be searched by LIB$FFx. The size argument is the
address of an unsigned byte containing the size of the bit field to
be searched. The maximum size is 32 bits.
base
VMS usage: address
type: longword (unsigned)
access: read only
mechanism: by reference
Base address of the bit field which LIB$FFx searches. The base
argument is the address of an unsigned longword containing the base
address.
find-position
VMS usage: longword_signed
type: longword integer (signed)
access: write only
mechanism: by reference
Bit position of the first bit in the specified state (clear or set),
relative to the base address. The find-position argument is the
address of a signed longword integer into which LIB$FFC writes the
position of the first clear bit and into which LIB$FFS writes the
position of the first set bit.
LIB$FID_TO_NAME
The Convert Device and File ID to File Specification routine
converts a disk device name and file identifier to a file
specification.
Format:
LIB$FID_TO_NAME device-name ,file-id ,file-spec
[,file-spec-length] [,directory-id] [,acp-status]
Arguments:
device-name
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
Device name to be converted. The device-name argument is the
address of a descriptor pointing to the device name. Device-name
must reference a disk device, and must contain 64 characters or
less. LIB$FID_TO_NAME obtains device-name from the NAM$T_DVI field
of a VAX RMS name block.
file-id
VMS usage: vector_word_unsigned
type: word (unsigned)
access: read only
mechanism: by reference
Specifies the file identifier. The file-id argument is the address
of an array of three words containing the file identification.
LIB$FID_TO_NAME obtains file-id from the NAM$W_FID field of a VAX
RMS name block. The $FIDDEF macro defines the structure of file-id.
file-spec
VMS usage: char_string
type: character string
access: write only
mechanism: by descriptor
Receives the file specification. The file-spec argument is the
address of a descriptor pointing to the file specification string.
file-spec-length
VMS usage: word_unsigned
type: word (unsigned)
access: write only
mechanism: by reference
Receives the number of characters written into file-spec, excluding
padding in the case of a fixed-length string. The optional
file-spec-length argument is the address of an unsigned word
containing the number of characters.
directory-id
VMS usage: vector_word_unsigned
type: word (unsigned)
access: read only
mechanism: by reference
Specifies a directory file identifier. The directory-id argument is
the address of an array of three words containing the directory file
identifier. LIB$FID_TO_NAME obtains this array from the NAM$W_DID
field of a VAX RMS name block. The $FIDDEF macro defines the
structure of directory-id.
acp-status
VMS usage: longword_unsigned
type: longword (unsigned)
access: write only
mechanism: by reference
The status resulting from traversing the backward links. The
optional acp-status argument is the address of an unsigned longword
containing the status.
LIB$FILE_SCAN
The File Scan routine searches an area, such as a directory, for all
files matching the file specification given and transfers program
execution to the specified user-written routine. Wildcards are
acceptable. An action routine is called for each file and/or error
found. LIB$FILE_SCAN allows the search sequence to continue even if
an error occurs while processing a particular file.
Format:
LIB$FILE_SCAN fab ,user-success-routine ,user-error-routine
[,context]
Arguments:
fab
VMS usage: fab
type: unspecified
access: read only
mechanism: by reference
File Access Block (FAB) referencing a valid NAM block. The fab
argument is the address of the FAB which contains the address and
length of the file specification being searched for by
LIB$FILE_SCAN.
user-success-routine
VMS usage: procedure
type: procedure entry mask
access: function call (before return)
mechanism: by value
User-supplied success routine that LIB$FILE_SCAN calls when a file
is found. The user-success-routine argument is the address of the
procedure entry mask to the success routine. The success routine is
invoked with the FAB address that was passed to LIB$FILE_SCAN. The
user context may be pased to this routine using the FAB$L_CTX field
in the FAB.
user-error-routine
VMS usage: procedure
type: procedure entry mask
access: function call (before return)
mechanism: by value
User-supplied error routine that LIB$FILE_SCAN calls when it
encounters an error. The user-error-routine argument is the address
of the procedure entry mask to the error routine. The error routine
is called with the FAB argument that was passed to LIB$FILE_SCAN.
context
VMS usage: context
type: longword (unsigned)
access: modify
mechanism: by reference
Default file context used in processing file specifications for
multiple input files. The context argument is the address of a
longword, which must be initialized to zero by your program before
the first call to LIB$FILE_SCAN. After the first call,
LIB$FILE_SCAN maintains this longword. You must not change the
value of context in subsequent calls to LIB$FILE_SCAN.
LIB$FILE_SCAN_END
The End of File Scan routine is called after each sequence of calls
to LIB$FILE_SCAN. LIB$FILE_SCAN_END deallocates any saved Record
Management Service (RMS) context and/or deallocates the virtual
memory that had been allocated for holding the related file
specification information.
Format:
LIB$FILE_SCAN_END [fab] [,context]
Arguments:
fab
VMS usage: fab
type: unspecified
access: modify
mechanism: by reference
File access block (FAB) used with LIB$FILE_SCAN. The optional fab
argument is the address of the FAB that contains the address and
length of the file specification.
context
VMS usage: context
type: longword (unsigned)
access: modify
mechanism: by reference
Temporary default context used in LIB$FILE_SCAN. The optional
context argument is the address of a longword containing this
temporary default context.
LIB$FIND_FILE
The Find File routine is called with a wildcard file specification
for which it searches. LIB$FIND_FILE returns all file
specifications that satisfy that wildcard file specification.
Format:
LIB$FIND_FILE filespec ,resultant-filespec ,context
[,default-filespec] [,related-filespec]
[,status-value] [,flags]
Arguments:
filespec
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
File specification, which may contain wildcards, that LIB$FIND_FILE
uses to search for the desired file. The filespec argument is the
address of a descriptor pointing to the file specification. The
maximum length of a file specification is 255 bytes.
resultant-filespec
VMS usage: char_string
type: character string
access: modify
mechanism: by descriptor
Resultant file specification that LIB$FIND_FILE returns when it
finds a file that matches the specification in the filespec
argument. The resultant-filespec argument is the address of a
descriptor pointing to the resultant file specification.
context
VMS usage: context
type: longword (unsigned)
access: modify
mechanism: by reference
Zero or an address of an internal FAB/NAM buffer from a previous
call to LIB$FIND_FILE. The context argument is an unsigned longword
integer containing the address of the context. LIB$FIND_FILE uses
this argument to retain the context when processing multiple input
files. Portions of file specifications that the user does not
specify are inherited from the last files processed because the file
contexts are retained in this argument.
default-filespec
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
Default file specification. The default-filespec argument is the
address of a descriptor pointing to the default file specification.
related-filespec
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
Related file specification containing the context of the last file
processed. The related-filespec argument is the address of a
descriptor pointing to the related file specification.
status-value
VMS usage: longword_unsigned
type: longword (unsigned)
access: write only
mechanism: by reference
Record Management Service (RMS) secondary status value from a
failing RMS operation. The status-value argument is an unsigned
longword containing the address of a longword-length buffer to
receive the RMS secondary status value (usually returned in the file
access block field, FAB$L_STV).
flags
VMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
User flags. The flags argument is the address of an unsigned
longword containing the user flags.
LIB$FIND_FILE_END
The End of Find File routine is called once after each sequence of
calls to LIB$FIND_FILE. LIB$FIND_FILE_END deallocates any saved
Record Management Service (RMS) context and deallocates the virtual
memory used to hold the allocated context block.
Format:
LIB$FIND_FILE_END context
Arguments:
context
VMS usage: context
type: longword (unsigned)
access: read only
mechanism: by reference
Zero or the address of a FAB/NAM buffer from a previous call to
LIB$FIND_FILE. The context argument is the address of a longword
that contains this context.
LIB$FIND_IMAGE_SYMBOL
The Find Universal Symbol in Shareable Image File routine reads
universal symbols from the shareable image file. This routine then
dynamically activates a shareable image into the P0 address space of
a process.
Format:
LIB$FIND_IMAGE_SYMBOL filename ,symbol ,symbol-value
Arguments:
filename
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
Name of the file for which LIB$FIND_IMAGE_SYMBOL is searching. The
filename argument is the address of a descriptor pointing to this
file name string. This argument may contain only the file name.
File type cannot be indicated. If any file specification
punctuation characters (:, [, <, .) are present, the error
SS$_IVLOGNAM is returned.
symbol
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
Symbol for which LIB$FIND_IMAGE_SYMBOL is searching in the filename
file. The symbol argument is the address of a descriptor pointing
to the symbol name string. The symbol name string must be input in
uppercase letters; this routine does not perform uppercase
conversion.
symbol-value
VMS usage: longword_signed
type: longword (signed)
access: write only
mechanism: by reference
Symbol value that LIB$FIND_IMAGE_SYMBOL has located. The
symbol-value argument is the address of a signed longword integer
into which LIB$FIND_IMAGE_SYMBOL returns the symbol value. If the
symbol is relocatable, the starting virtual address of the shareable
image in memory will be added to the symbol value.
LIB$FIND_VM_ZONE
The Return the Next Valid Zone Identifier routine returns the zone
identifier of the next valid zone in the heap management database.
Format:
LIB$FIND_VM_ZONE context ,zone-id
Arguments:
context
VMS usage: context
type: longword (unsigned)
access: modify
mechanism: by reference
Context specifier. The context argument is the address of an
unsigned longword used to keep the scan context for finding the next
valid zone. Context must be 0 to initialize the scan and to start
with the first returnable zone id.
zone-id
VMS usage: identifier
type: longword (unsigned)
access: write only
mechanism: by reference
Zone identifier. The zone-id argument is the address of an unsigned
longword that receives the zone identifier for the next zone.
LIB$FIXUP_FLT
The Fix Floating Reserved Operand routine finds the reserved operand
of any F_floating, D_floating, G_floating, or H_floating instruction
(with some exceptions) after a reserved operand fault has been
signaled. LIB$FIXUP_FLT changes the reserved operand from --0.0 to
the value of the new-operand argument, if present; or to +0.0 if
new-operand is absent.
Format:
LIB$FIXUP_FLT signal-arguments ,mechanism-arguments
[,new-operand]
Arguments:
signal-arguments
VMS usage: vector_longword_unsigned
type: unspecified
access: read only
mechanism: by reference, array reference
Signal argument vector. The signal-arguments argument is the
address of an array of unsigned longwords containing the signal
argument vector.
mechanism-arguments
VMS usage: vector_longword_unsigned
type: unspecified
access: read only
mechanism: by reference, array reference
Mechanism argument vector. The mechanism-arguments argument is the
address of an array of unsigned longwords containing the mechanism
argument vector.
new-operand
VMS usage: floating-point
type: F_floating
access: read only
mechanism: by reference
An F_floating value to replace the reserved operand. The
new-operand argument is the address of an F_floating number
containing the new operand. This is an optional argument. If
omitted, the default value is +0.0.
LIB$FLT_UNDER
The Floating-Point Underflow Detection routine enables or disables
floating-point underflow detection for the calling procedure
activation. The previous setting is returned as a function value.
Format:
LIB$FLT_UNDER new-setting
Argument
new-setting
VMS usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
New floating-point underflow enable setting. The new-setting
argument is the address of an unsigned byte containing the new
setting. Bit 0 set to 1 means enable; bit 0 set to 0 means disable.
LIB$FORMAT_DATE_TIME
The Format Date And/Or Time routine allows the user to select at run
time a specific output language and format for a date and/or time.
Format:
LIB$FORMAT_DATE_TIME date-string [,date] [,user-context]
[,date-length] [,flags]
Arguments:
date-string
VMS usage: char_string
type: character string
access: write only
mechanism: by descriptor
Receives the requested date and/or time in the specified format.
The date-string argument is the address of a descriptor pointing to
this string.
date
VMS usage: date_time
type: quadword (unsigned)
access: read only
mechanism: by reference
The date and/or time to be formatted for output. The date argument
is the address of an unsigned quadword that contains the absolute
date and/or time to be formatted. If you omit this argument, or if
you supply a zero passed by value, then the current system time is
used. Note that the date argument must represent an absolute time,
not a delta time.
user-context
VMS usage: context
type: longword (unsigned)
access: modify
mechanism: by reference
User context that maintains information used by this routine. The
user-context argument is the address of an unsigned longword
containing this context. If you omit the user-context argument,
this context information is maintained internally, and the routine
invocation is not reentrant.
date-length
VMS usage: word_unsigned
type: word (unsigned)
access: write only
mechanism: by reference
Number of bytes of text (not characters) written to the date-string
argument. The date-length argument is the address of an unsigned
word that receives this string length. Note that date-length
specifies the number of bytes of text, not the number of characters,
written to date-string.
flags
VMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Bit mask that allows the user to specify whether the date, time, or
both are output. The flags argument is the address of an unsigned
bit mask containing the specified values. Valid values are
LIB$M_DATE_FIELDS and LIB$M_TIME_FIELDS.
LIB$FREE_DATE_TIME_CONTEXT
The Free The Context Area Used When Formatting Date And/Or Time
routine frees the virtual memory associated with the context area
used by the date/time formatting routines.
Format:
LIB$FREE_DATE_TIME_CONTEXT [user-context]
Arguments:
user-context
VMS usage: context
type: longword (unsigned)
access: modify
mechanism: by reference
Context variable passed to the LIB$FORMAT_DATE_TIME routine. The
user-context argument is the address of an unsigned longword that
contains this context. If the user-context argument was not
specified in the call to LIB$FORMAT_DATE_TIME or
LIB$CONVERT_DATE_STRING, then no argument should be passed when
calling LIB$FREE_DATE_TIME_CONTEXT.
LIB$FREE_EF
The Free Event Flag routine frees a local event flag previously
allocated by LIB$GET_EF. LIB$FREE_EF is the complement of
LIB$GET_EF.
Format:
LIB$FREE_EF event-flag-number
Argument
event-flag-number
VMS usage: ef_number
type: longword integer (unsigned)
access: read only
mechanism: by reference
Event flag number to be deallocated by LIB$FREE_EF. The
event-flag-number argument is the address of a signed longword
integer that contains the event flag number, which is the value
returned to the user by LIB$GET_EF.
LIB$FREE_LUN
The Free Logical Unit Number routine releases a logical unit number
allocated by LIB$GET_LUN to the pool of available numbers.
LIB$FREE_LUN is the complement of LIB$GET_LUN.
Format:
LIB$FREE_LUN logical-unit-number
Argument
logical-unit-number
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Logical unit number to be deallocated. The logical-unit-number
argument is the address of a signed longword integer that contains
this logical unit number, which is the value previously returned by
LIB$GET_LUN.
LIB$FREE_TIMER
The Free Timer Storage routine frees the storage allocated by
LIB$INIT_TIMER.
Format:
LIB$FREE_TIMER handle-address
Argument
handle-address
VMS usage: address
type: longword (unsigned)
access: modify
mechanism: by reference
Pointer to a block of storage containing the value returned by a
previous call to LIB$INIT_TIMER; this is the storage that
LIB$FREE_TIMER deallocates. The handle-address argument is the
address of an unsigned longword containing that value.
LIB$FREE_VM
The Free Virtual Memory from Program Region routine deallocates an
entire block of contiguous bytes that were allocated by a previous
call to LIB$GET_VM. The arguments passed are the same as for
LIB$GET_VM.
Format:
LIB$FREE_VM number-of-bytes ,base-address [,zone-id]
Arguments:
number-of-bytes
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Number of contiguous bytes to be deallocated by LIB$FREE_VM. The
number-of-bytes argument is the address of a signed longword integer
that contains this number. The value of number-of-bytes must be
greater than zero.
base-address
VMS usage: address
type: longword (unsigned)
access: read only
mechanism: by reference
Address of the first byte to be deallocated by LIB$FREE_VM. The
base-address argument contains the address of an unsigned longword
that is this address. The value of base-address must be the address
of a block of memory that was allocated by a previous call to
LIB$GET_VM.
zone-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
The zone-id argument is the address of a longword that contains a
zone identifier created by a previous call to LIB$CREATE_VM_ZONE or
LIB$CREATE_USER_VM_ZONE.
LIB$FREE_VM_PAGE
The Free Virtual Memory Page routine deallocates a block of
contiguous pages that were allocated by previous calls to
LIB$GET_VM_PAGE.
Format:
LIB$FREE_VM_PAGE number-of-pages ,base-address
Arguments:
number-of-pages
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Number of pages. The number-of-pages argument is the address of a
longword integer which specifies the number of contiguous pages to
be deallocated. The value of number-of-pages must be greater than
zero.
base-address
VMS usage: address
type: longword (unsigned)
access: read only
mechanism: by reference
Block address. The base-address argument is the address of a
longword which contains the address of the first byte of the first
page to be deallocated.
LIB$GETDVI
The Get Device/Volume Information routine provides a simplified
interface to the $GETDVI system service. It returns information
about the primary and secondary device characteristics of an I/O
device. The calling process need not have a channel assigned to the
device about which it wants information.
Format:
LIB$GETDVI item-code [,channel] [,device-name]
[,longword-integer-value] [,resultant-string]
[,resultant-length]
Arguments:
item-code
VMS usage: word_unsigned
type: word (unsigned)
access: read only
mechanism: by reference
Code specifying the item of information you are requesting. The
item-code argument is the address of an unsigned word integer
containing the item code. All valid $GETDVI item codes whose names
begin with DVI$_ are accepted.
channel
VMS usage: channel
type: word (unsigned)
access: read only
mechanism: by reference
VMS I/O channel assigned to the device for which LIB$GETDVI returns
information. The channel argument is the address of an unsigned
word containing the channel specification. If channel is not
specified, device-name is used instead. You must specify either
channel or device-name, but not both. If neither is specified, the
error status SS$_IVDEVNAM is returned.
device-name
VMS usage: device_name
type: character string
access: read only
mechanism: by descriptor
Name of the device for which LIB$GETDVI returns information. The
device-name argument is the address of a descriptor pointing to the
device name string. If this string contains a colon, the colon and
the characters that follow it are ignored.
longword-integer-value
VMS usage: longword_signed
type: longword (signed)
access: write only
mechanism: by reference
Numeric value of the information requested. The
longword-integer-value argument is the address of a signed longword
containing the numeric value. If an item is listed as only
returning a string value, this argument is ignored.
resultant-string
VMS usage: char_string
type: character string
access: write only
mechanism: by descriptor
String representation of the information requested. The
resultant-string argument is the address of a descriptor pointing to
this information. If resultant-string is not specified and if the
value returned has only a string representation, the error status
LIB$_INVARG is returned.
resultant-length
VMS usage: word_unsigned
type: word (unsigned)
access: write only
mechanism: by reference
Number of significant characters written to resultant-string by
LIB$GETDVI. The resultant-length argument is the address of an
unsigned word containing this length.
LIB$GETJPI
The Get Job/Process Information routine provides a simplified
interface to the $GETJPI system service. It provides accounting,
status, and identification information about a specified process.
LIB$GETJPI obtains only one item of information in a single call.
Format:
LIB$GETJPI item-code [,process-id] [,process-name]
[,resultant-value] [,resultant-string]
[,resultant-length]
Arguments:
item-code
VMS usage: word_unsigned
type: word (unsigned)
access: read only
mechanism: by reference
Item identifier code specifying the item of information you are
requesting. The item-code argument is the address of an unsigned
word integer containing the item code. You may request only one
item in each call to LIB$GETJPI.
process-id
VMS usage: process_id
type: longword (unsigned)
access: modify
mechanism: by reference
Process identification of the process for which you are requesting
information. The process-id argument is the address of an unsigned
longword containing the process identification. If you do not
specify process-id, process-name is used.
process-name
VMS usage: process_name
type: character string
access: read only
mechanism: by descriptor
A 1- to 15-character string specifying the name of the process for
which you are requesting information. The name must correspond
exactly to the name of the process for which you are requesting
information; LIB$GETJPI does not allow trailing blanks or
abbreviations.
resultant-value
VMS usage: varying_arg
type: unspecified
access: write only
mechanism: by reference
Numeric value of the information you request. The resultant-value
argument is the address of a longword or quadword into which
LIB$GETJPI writes the numeric value of this information. If the item
you request returns only a string value, this argument is ignored.
resultant-string
VMS usage: char_string
type: character string
access: write only
mechanism: by descriptor
String representation of the information you request. The
resultant-string argument is the address of a character string into
which LIB$GETJPI writes the string representation.
resultant-length
VMS usage: word_unsigned
type: word (unsigned)
access: write only
mechanism: by reference
Number of significant characters written to resultant-string by
LIB$GETJPI. The resultant-length argument is the address of an
unsigned word integer into which LIB$GETJPI writes the number of
characters.
LIB$GETQUI
The Get Queue Information routine provides a simplified interface to
the $GETQUI system service. It provides queue, job, file,
characteristic, and form information about a specified process.
LIB$GETQUI obtains only one item of information in a single call.
Format:
LIB$GETQUI function-code [,item-code] [,search-number]
[,search-name] [,search-flags] [,resultant-value]
[,resultant-string] [,resultant-length]
Arguments:
function-code
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Function code specifying the function that LIB$GETQUI is to perform.
The function-code argument is the address of a signed longword
integer containing the function code.
item-code
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Item identifier code specifying the item of information you are
requesting. The item-code argument is the address of a signed
longword integer containing the item code. You may request only one
item in each call to LIB$GETQUI.
search-number
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Numeric value used to process your request. The search-number
argument is the address of a signed longword integer containing the
number needed to process your request. Search-number directly
corresponds to QUI$_SEARCH_NUMBER as described by the $GETQUI system
service.
search-name
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
Character string used to process your request. The search-name
argument is the address of a string descriptor that provides the
name needed to process your request. Search-name directly
corresponds to QUI$_SEARCH_NAME as described by the $GETQUI system
service.
search-flags
VMS usage: longword_unsigned
type: longword integer (unsigned)
access: read only
mechanism: by reference
Optional bit mask indicating request to be performed. The
search-flags argument is the address of an unsigned longword integer
containing the bit mask. Search-flags directly corresponds to
$QUI_SEARCH_FLAGS as described by the $GETQUI system service.
resultant-value
VMS usage: varying_arg
type: unspecified
access: write only
mechanism: by reference
Numeric value of the information you requested. The resultant-value
argument is the address of a longword, quadword or octaword into
which LIB$GETQUI writes the numeric value of this information.
If the item you requested returns only a string value, this argument
is ignored.
resultant-string
VMS usage: char_string
type: character string
access: write only
mechanism: by descriptor
String representation of the information you requested. The
resultant-string argument is the address of a character string into
which LIB$GETQUI writes the string representation.
resultant-length
VMS usage: word_signed
type: word integer (signed)
access: write only
mechanism: by reference
Number of significant characters written to resultant-string by
LIB$GETQUI. The resultant-length argument is the address of a
signed word integer into which LIB$GETQUI writes the number of
characters.
LIB$GETSYI
The Get Systemwide Information routine provides a simplified
interface to the $GETSYI system service. The $GETSYI system service
obtains status and identification information about the system.
LIB$GETSYI returns only one item of information in a single call.
Format:
LIB$GETSYI item-code [,resultant-value] [,resultant-string]
[,resultant-length] [,cluster-system-id] [,node-name]
Arguments:
item-code
VMS usage: word_unsigned
type: word (unsigned)
access: read only
mechanism: by reference
Item code specifying the desired item of information. The item-code
argument is the address of an unsigned word integer containing this
item code. All valid $GETSYI item codes are accepted.
resultant-value
VMS usage: varying_arg
type: unspecified
access: write only
mechanism: by reference
Numeric value returned by LIB$GETSYI. The resultant-value argument
is the address of a longword or quadword containing this value. If
an item is listed as returning only a string value, this argument is
ignored.
resultant-string
VMS usage: char_string
type: character string
access: write only
mechanism: by descriptor
Information returned by LIB$GETSYI. The resultant-string argument
is the address of a descriptor pointing to the character string that
will receive this information.
resultant-length
VMS usage: word_unsigned
type: word (unsigned)
access: write only
mechanism: by reference
Number of significant characters written to resultant-string, not
including blank padding or truncated characters. The
resultant-length argument is the address of an unsigned word into
which LIB$GETSYI returns this number.
cluster-system-id
VMS usage: identifier
type: longword (unsigned)
access: modify
mechanism: by reference
Cluster system identification (CSID) of the node for which
information is to be returned. The cluster-system-id argument is
the address of this CSID. If cluster-system-id is specified and is
non-zero, node-name is not used. If cluster-system-id is specified
as zero, LIB$GETSYI uses node-name and writes into the
cluster-system-id argument the CSID corresponding to the node
identified by node name.
node-name
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
Name of the node for which information is to be returned. The
node-name argument is the address of a descriptor pointing to the
node name string. If cluster-system-id is not specified or is
specified as zero, node-name is used. If neither node-name nor
cluster-system-id is specified, the caller's node is used. See the
cluster-system-id argument for more information.
LIB$GET_COMMAND
The Get Line from SYS$COMMAND routine gets one record of ASCII text
from the current controlling input device, specified by the logical
name SYS$COMMAND.
Format:
LIB$GET_COMMAND resultant-string [,prompt-string]
[,resultant-length]
Arguments:
resultant-string
VMS usage: char_string
type: character string
access: write only
mechanism: by descriptor
String that LIB$GET_COMMAND gets from SYS$COMMAND. The
resultant-string argument is the address of a descriptor pointing to
this string.
prompt-string
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
Prompt message that LIB$GET_COMMAND displays on the controlling
terminal. The prompt-string argument is the address of a descriptor
pointing to the prompt. A valid prompt consists of text followed by
no carriage-return/line-feed combination. A colon(:) and one space
are optional.
resultant-length
VMS usage: word_unsigned
type: word (unsigned)
access: write only
mechanism: by reference
Number of bytes written into resultant-string by LIB$GET_COMMAND,
not counting padding in the case of a fixed string. The
resultant-length argument is the address of an unsigned word
containing this length. If the input string is truncated to the
size specified in the resultant-string descriptor, resultant-length
is set to this size. Therefore, resultant-length can always be used
by the calling program to access a valid substring of
resultant-string.
LIB$GET_COMMON
The Get String from Common routine copies a string in the common
area to the destination string. (The common area is an area of
storage which remains defined across multiple image activations in a
process.) The string length is taken from the first longword of the
common area.
Format:
LIB$GET_COMMON resultant-string [,resultant-length]
Arguments:
resultant-string
VMS usage: char_string
type: character string
access: write only
mechanism: by descriptor
Destination string into which LIB$GET_COMMON writes the string
copied from the common area. The resultant-string argument is the
address of a descriptor pointing to the destination string.
resultant-length
VMS usage: word_unsigned
type: word (unsigned)
access: write only
mechanism: by reference
Number of characters written into resultant-string by
LIB$GET_COMMON, not counting padding in the case of a fixed-length
string. The resultant-length argument is the address of an unsigned
word integer containing the number of characters copied. If the
input string is truncated to the size specified in the
resultant-string descriptor, resultant-length is set to this size.
Therefore, resultant-length can always be used by the calling
program to access a valid substring of resultant-string.
LIB$GET_DATE_FORMAT
The Get The User's Date Input Format routine returns information
about the user's choice of a date/time input format.
Format:
LIB$GET_DATE_FORMAT format-string [,user-context]
Arguments:
format-string
VMS usage: char_string
type: character string
access: write only
mechanism: by descriptor
Receives the translation of LIB$DT_INPUT_FORMAT. The format-string
argument is the address of a descriptor pointing to this format
string.
user-context
VMS usage: context
type: longword (unsigned)
access: modify
mechanism: by reference
Context variable that retains the translation context over multiple
calls to this routine. The user-context argument is the address of
an unsigned longword that contains this context. The initial value
of the context variable must be zero. Thereafter, the user program
must not write to the cell.
LIB$GET_EF
The Get Event Flag routine allocates one local event flag from a
process-wide pool and returns the number of the allocated flag to
the caller. If no flags are available, LIB$GET_EF returns an error
as its function value.
Format:
LIB$GET_EF event-flag-number
Argument
event-flag-number
VMS usage: ef_number
type: longword (unsigned)
access: write only
mechanism: by reference
Number of the local event flag that LIB$GET_EF allocated, or --1 if
no local event flag was available. The event-flag-number argument
is the address of a signed longword integer into which LIB$GET_EF
writes the number of the local event flag that it allocates.
LIB$GET_FOREIGN
The Get Foreign Command Line routine requests the calling image's
Command Language Interpreter (CLI) to return the contents of the
"foreign command" line that activated the current image.
Format:
LIB$GET_FOREIGN resultant-string [,prompt-string]
[,resultant-length] [,flags]
Arguments:
resultant-string
VMS usage: char_string
type: character string
access: write only
mechanism: by descriptor
String which LIB$GET_FOREIGN uses to receive the foreign command
line. The resultant-string argument is the address of a descriptor
pointing to this string. If the foreign command text returned was
obtained by prompting to SYS$INPUT (see the description of flags),
the text is translated to uppercase so as to be more consistent with
text returned from the CLI.
prompt-string
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
Optional user-supplied prompt for text which LIB$GET_FOREIGN uses if
no command-line text is available. The prompt-string argument is
the address of a descriptor pointing to the user prompt. If
omitted, no prompting is performed. It is recommended that
prompt-string be specified. If prompt-string is omitted and if no
command-line text is available, a zero-length string will be
returned.
resultant-length
VMS usage: word_unsigned
type: word (unsigned)
access: write only
mechanism: by reference
Number of bytes written into resultant-string by LIB$GET_FOREIGN,
not counting padding in the case of a fixed-length resultant-string.
The resultant-length argument is the address of an unsigned word
into which LIB$GET_FOREIGN writes the number of bytes.
flags
VMS usage: mask_longword
type: longword (unsigned)
access: modify
mechanism: by reference
Value which LIB$GET_FOREIGN uses to control whether or not prompting
is to be performed. The flags argument is the address of a signed
longword integer containing this value. If the low bit of flags is
zero, or if flags is omitted, prompting is done only if the CLI does
not return a command line. If the low bit is 1, prompting is done
unconditionally. If specified, flags is set to 1 before returning
to the caller.
LIB$GET_INPUT
The Get Line from SYS$INPUT routine gets one record of ASCII text
from the current controlling input device, specified by SYS$INPUT.
Format:
LIB$GET_INPUT resultant-string [,prompt-string]
[,resultant-length]
Arguments:
resultant-string
VMS usage: char_string
type: character string
access: write only
mechanism: by descriptor
String which LIB$GET_INPUT gets from the input device. The
resultant-string argument is the address of a descriptor pointing to
the character string into which LIB$GET_INPUT writes the text
received from the current input device.
prompt-string
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
Prompt message that is displayed on the controlling terminal. The
prompt-string argument is the address of a descriptor containing the
prompt. A valid prompt consists of text followed by a colon (:), a
space, and no carriage-return/line-feed combination. The maximum
size of the prompt message is 255 characters. If the controlling
input device is not a terminal, this argument is ignored.
resultant-length
VMS usage: word_unsigned
type: word (unsigned)
access: write only
mechanism: by reference
Number of bytes written into resultant-string by LIB$GET_INPUT, not
counting padding in the case of a fixed string. The
resultant-length argument is the address of an unsigned word
containing this number. If the input string is truncated to the
size specified in the resultant-string descriptor, resultant-length
is set to this size. Therefore, resultant-length can always be used
by the calling program to access a valid substring of
resultant-string.
LIB$GET_LUN
The Get Logical Unit Number routine allocates one logical unit
number from a process-wide pool. If a unit is available, its number
is returned to the caller. Otherwise, an error is returned as the
function value.
Format:
LIB$GET_LUN logical-unit-number
Arguments:
logical-unit-number
VMS usage: longword_signed
type: longword integer (signed)
access: write only
mechanism: by reference
Allocated logical unit number or --1 if none was available. The
logical-unit-number argument is the address of a longword into which
LIB$GET_LUN returns the value of the allocated logical unit.
LIB$GET_MAXIMUM_DATE_LENGTH
Given an output format and language, the Retrieve the Maximum Length
of a Date/Time String routine determines the maximum possible length
for the date-string string returned by LIB$FORMAT_DATE_TIME.
Format:
LIB$GET_MAXIMUM_DATE_LENGTH date-length [,user-context]
[,flags]
Arguments:
date-length
VMS usage: longword_signed
type: longword (signed)
access: write only
mechanism: by reference
Receives the maximum possible length of the date-string argument
returned by LIB$FORMAT_DATE_TIME. The date-length argument is the
address of a signed longword that receives this maximum length. The
length written to date-length reflects the greatest possible length
of an output date/time string for the currently selected output
format and natural language.
user-context
VMS usage: context
type: longword (unsigned)
access: modify
mechanism: by reference
Context variable that retains the translation context over multiple
calls to this routine. The user-context argument is the address of
an unsigned longword that contains this context. The initial value
of the context variable must be zero. Thereafter, the user program
must not write to the cell.
flags
VMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Bit mask that allows the user to specify whether the date, time, or
both are to be included in the calculation of the maximum date
length. The flags argument is the address of an unsigned bit mask
containing the specified values. Valid values are LIB$M_DATE_FIELDS
and LIB$M_TIME_FIELDS. The values specified for flags must
correspond to the flags argument passed to LIB$FORMAT_DATE_TIME.
LIB$GET_SYMBOL
The Get Value of CLI Symbol routine requests the calling process's
Command Language Interpreter (CLI) to return the value of a CLI
symbol as a string. LIB$GET_SYMBOL then returns the string to the
caller. Optionally, LIB$GET_SYMBOL can return the length of the
returned value and the table in which the symbol was found.
Format:
LIB$GET_SYMBOL symbol ,resultant-string [,resultant-length]
[,table-type-indicator]
Arguments:
symbol
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
Name of the symbol for which LIB$GET_SYMBOL searches. The symbol
argument is the address of a descriptor pointing to the name of the
symbol. LIB$GET_SYMBOL converts the symbol name to uppercase and
removes trailing blanks before the search. Symbol must begin with a
letter or dollar sign ($). The maximum length of symbol is 255
characters.
resultant-string
VMS usage: char_string
type: character string
access: write only
mechanism: by descriptor
Value of the returned symbol. The resultant-string argument is the
address of a descriptor pointing to a character string into which
LIB$GET_SYMBOL writes the value of the symbol.
resultant-length
VMS usage: word_unsigned
type: word (unsigned)
access: write only
mechanism: by reference
Length of the symbol value returned by LIB$GET_SYMBOL. The
resultant-length argument is the address of an unsigned word integer
into which LIB$GET_SYMBOL writes the length.
table-type-indicator
VMS usage: longword_signed
type: longword integer (signed)
access: write only
mechanism: by reference
Indicator of which table contained the symbol. The
table-type-indicator argument is the address of a signed longword
integer into which LIB$GET_SYMBOL writes the table indicator.
LIB$GET_USERS_LANGUAGE
The Return The User's Language routine determines the user's choice
of a natural language. The choice is determined by translating the
logical SYS$LANGUAGE.
Format:
LIB$GET_USERS_LANGUAGE language
Arguments:
language
VMS usage: char_string
type: character string
access: write only
mechanism: by descriptor
Receives the translation of SYS$LANGUAGE. The language argument is
the address of a descriptor pointing to this language name.
LIB$GET_VM
The Allocate Virtual Memory routine allocates a specified number of
contiguous bytes in the program region and returns the virtual
address of the first byte allocated.
Format:
LIB$GET_VM number-of-bytes, base-address [,zone-id]
Arguments:
number-of-bytes
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Number of contiguous bytes that LIB$GET_VM allocates. The
number-of-bytes argument is the address of a longword integer
containing the number of bytes. LIB$GET_VM allocates enough memory
to satisfy the request. Your program should not reference an
address before the first byte address allocated (base-address) or
beyond the last byte allocated (base-address + number-of-bytes -- 1)
since that space may be assigned to another procedure. The value of
number-of-bytes must be greater than zero.
base-address
VMS usage: address
type: longword (unsigned)
access: write only
mechanism: by reference
First virtual address of the contiguous block of bytes allocated by
LIB$GET_VM. The base-address argument is the address of an unsigned
longword containing this base address.
zone-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
The zone-id argument is the address of a longword that contains a
zone identifier created by a previous call to LIB$CREATE_VM_ZONE or
LIB$CREATE_USER_VM_ZONE. This argument is optional. If zone-id is
omitted or if the longword contains the value 0, LIB$VM's default
zone is used.
LIB$GET_VM_PAGE
The Get Virtual Memory Page routine allocates a specified number of
contiguous pages of memory in the program region and returns the
virtual address of the first page allocated.
Format:
LIB$GET_VM_PAGE number-of-pages ,base-address
Arguments:
number-of-pages
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Number of pages. The number-of-pages argument is the address of a
longword integer which specifies the number of contiguous pages to
be allocated. The value of number-of-pages must be greater than
zero.
base-address
VMS usage: address
type: longword (unsigned)
access: write only
mechanism: by reference
Block address. The base-address argument is the address of a
longword which is set to the address of the first byte of the newly
allocated block of pages.
LIB$ICHAR
The Convert First Character of String to Integer routine converts
the first character of a source string to an 8-bit ASCII integer
extended to a longword.
Format:
LIB$ICHAR source-string
ARGUMENT
source-string
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
Source string whose first character is converted to an integer by
LIB$ICHAR. The scr-str argument is the address of a descriptor
pointing to this source string.
LIB$INDEX
The Index to Relative Position of Substring routine returns an
index, which is the relative position of the first occurrence of a
substring in the source string.
Format:
LIB$INDEX source-string ,sub-string
Arguments:
source-string
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
Source string to be searched by LIB$INDEX. The source-string
argument is the address of a descriptor pointing to this source
string.
sub-string
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
Substring to be found. The sub-string argument is the address of a
descriptor pointing to this substring.
LIB$INIT_DATE_TIME_CONTEXT
The Initialize The Context Area Used In Formatting Date And/Or Time
routine allows the user to preinitialize the context area used by
LIB$FORMAT_DATE_TIME or LIB$CONVERT_DATE_STRING with specific
strings, instead of through logical name translation.
Format:
LIB$INIT_DATE_TIME_CONTEXT user-context ,component
,init-string
Arguments:
user-context
VMS usage: context
type: longword (unsigned)
access: modify
mechanism: by reference
Context defined by the user to maintain the context of the logical
name translations. The user-context argument is the address of an
unsigned longword that contains this context.
component
VMS usage: longword_signed
type: longword (signed)
access: read only
mechanism: by reference
The component of the context that is being initialized. The
component argument is the address of a signed longword that
indicates this component. Only one component can be initialized per
call to LIB$INIT_DATE_TIME; these component codes are
o LIB$K_MONTH_NAME
o LIB$K_MONTH_NAME_ABB
o LIB$K_FORMAT_MNEMONICS
o LIB$K_WEEKDAY_NAME
o LIB$K_WEEKDAY_NAME_ABB
o LIB$K_RELATIVE_DAY_NAME
o LIB$K_MERIDIEM_INDICATOR
o LIB$K_OUTPUT_FORMAT
o LIB$K_INPUT_FORMAT
init-string
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
The characters which are to be used in formatting date and/or time
text. The init-string argument is the address of a descriptor
pointing to this string.
LIB$INIT_TIMER
The Initialize Times and Counts routine stores the current values of
specified times and counts for use by LIB$SHOW_TIMER or
LIB$STAT_TIMER.
Format:
LIB$INIT_TIMER [context]
Argument
context
VMS usage: address
type: longword (unsigned)
access: modify
mechanism: by reference
Pointer to a control block where the values of times and counts will
be stored. The handle-address argument contains the address of an
unsigned longword that is this pointer. When you call
LIB$INIT_TIMER, you must use the optional handle-address argument
only if you want to maintain several sets of statistics
simultaneously.
o If handle-address is omitted, the control block is allocated in
static storage. This method is not AST reentrant.
o If handle-address is zero, a control block is allocated in
dynamic heap storage. The times and counts will be stored in
that block and the address of the block returned in
handle-address. This method is fully reentrant and modular.
o If handle-address is nonzero, it is considered to be the address
of a control block previously allocated by a call to
LIB$INIT_TIMER. If so, the control block is reused, and fresh
times and counts are stored in it.
LIB$INSERT_TREE
The Insert Entry in a Balanced Binary Tree routine inserts a node in
a balanced binary tree.
Format:
LIB$INSERT_TREE treehead ,symbol ,flags ,user-compare-routine
,user-allocation-routine ,new-node [,user-data]
Arguments:
treehead
VMS usage: longword_unsigned
type: longword (unsigned)
access: modify
mechanism: by reference
Tree head for the binary tree. The treehead argument is the address
of a longword that is this tree head.
symbol
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
Key to be inserted. The symbol argument is the address of a
descriptor pointing to the symbol key.
flags
VMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Control flags. The flags argument is the address of the control
flags. Currently only bit zero is used.
Bit Description
0 If clear, the address of the existing duplicate entry
is returned. If set, duplicate entries are inserted.
user-compare-routine
VMS usage: procedure
type: procedure entry mask
access: function call (before return)
mechanism: by value
User-supplied compare routine that LIB$INSERT_TREE calls to compare
a symbol with a node. The user-compare-routine argument is the
address of the entry mask to the compare routine. The
user-compare-routine argument is required; LIB$INSERT_TREE always
calls the compare routine. The value returned by the compare
routine indicates the relationship between the symbol key and the
node.
user-allocation-routine
VMS usage: procedure
type: procedure entry mask
access: function call (before return)
mechanism: by value
User-supplied allocate routine that LIB$INSERT_TREE calls to
allocate virtual memory for a node. The user-allocation-routine
argument is the address of the entry mask to the allocate routine.
The user-allocation-routine argument is required; LIB$INSERT_TREE
always calls the allocate routine.
new-node
VMS usage: address
type: longword (unsigned)
access: write only
mechanism: by reference
Location where the new key is inserted. The new-node argument is
the address of an unsigned longword that is this new node location.
user-data
VMS usage: user_arg
type: unspecified
access: unspecified
mechanism: unspecified
User data that LIB$INSERT_TREE passes to the compare and allocate
routines. User-data is an optional argument.
LIB$INSQHI
The Insert Entry at Head of Queue routine inserts a queue entry at
the head of the specified self-relative interlocked queue.
LIB$INSQHI makes the VMS INSQHI instruction available as a callable
procedure.
Format:
LIB$INSQHI entry ,header [,retry-count]
Arguments:
entry
VMS usage: unspecified
type: unspecified
access: modify
mechanism: by reference, array reference
Entry to be inserted by LIB$INSQHI. The entry argument contains the
address of this signed quadword-aligned array that must be at least
eight bytes long. Bytes following the first eight bytes can be used
for any purpose by the calling program.
header
VMS usage: quadword_signed
type: quadword integer (signed)
access: modify
mechanism: by reference
Queue header specifying the queue into which entry is to be
inserted. The header argument contains the address of this signed
aligned quadword integer. Header must be initialized to zero before
first use of the queue; zero means an empty queue.
retry-count
VMS usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
The number of times the insertion is to be retried in case of
secondary-interlock failure of the queue instruction in a
processor-shared memory application. The retry-count argument is
the address of an unsigned longword that contains the retry count
value. A value of 1 causes no retries. The default value is 10.
LIB$INSQTI
The Insert Entry at Tail of Queue routine inserts a queue entry at
the tail of the specified self-relative interlocked queue.
LIB$INSQTI makes the VAX INSQTI instruction available as a callable
procedure.
Format:
LIB$INSQTI entry ,header [,retry-count]
Arguments:
entry
VMS usage: unspecified
type: unspecified
access: modify
mechanism: by reference, array reference
Entry to be inserted at the tail of the queue by LIB$INSQTI. The
entry argument contains the address of this signed quadword-aligned
array that must be at least eight bytes long. Bytes following the
first eight bytes can be used for any purpose by the calling
program.
header
VMS usage: quadword_signed
type: quadword integer (signed)
access: modify
mechanism: by reference
Queue header specifying the queue into which the queue entry is to
be inserted. The header argument contains the address of this
signed aligned quadword integer. Header must be initialized to zero
before first use of the queue; zero means an empty queue.
retry-count
VMS usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
The number of times the insertion is to be retried in case of
secondary-interlock failure of the queue instruction in a
processor-shared memory application. The retry-count argument is
the address of a longword which contains the retry count value. The
default value is 10.
LIB$INSV
The Insert a Variable Bit Field routine replaces the variable bit
field specified by the base, position, and size arguments with bits
0 through ( size - 1) of the source field. If the size of the bit
field is zero, nothing is inserted. LIB$INSV makes the VAX INSV
instruction available as a callable procedure.
Format:
LIB$INSV longword-integer-source ,position ,size ,base-address
Arguments:
longword-integer-source
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Source field to be inserted by LIB$INSV. The
longword-integer-source argument is the address of a signed longword
integer that contains this source field.
position
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Bit position relative to the base address where insertion of
longword-integer-source is to begin. The position argument is the
address of a longword integer that contains this relative bit
position.
size
VMS usage: byte_unsigned
type: byte (unsigned)
access: read only
mechanism: by reference
Size of the bit field to be inserted by LIB$INSV. The size argument
is the address of an unsigned byte which contains the size of this
bit field. The maximum size is 32 bits.
base-address
VMS usage: address
type: unspecified
access: write only
mechanism: by reference
Field into which LIB$INSV writes the source field. The base-address
argument contains the base address of this aligned bit string.
LIB$INT_OVER
The Integer Overflow Detection routine enables or disables integer
overflow detection for the calling procedure activation. The
previous integer overflow enable setting is returned.
Format:
LIB$INT_OVER new-setting
Argument
new-setting
VMS usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
New integer overflow enable setting. The new-setting argument is
the address of an unsigned longword which contains the new integer
overflow enable setting. Bit 0 set to 1 means enable, bit 0 set to
0 means disable.
LIB$LEN
The Length of String Returned as Longword Value routine returns the
length of a string.
Format:
LIB$LEN source-string
Argument
source-string
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
Source string whose length is returned by LIB$LEN. The
source-string argument contains the address of a descriptor pointing
to this source string.
LIB$LOCC
The Locate a Character routine locates a character in a string by
comparing successive bytes in the string with the character
specified. The search continues until the character is found or the
string has no more characters. LIB$LOCC makes the VAX LOCC
instruction available as a callable procedure.
Format:
LIB$LOCC character-string ,source-string
Arguments:
character-string
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
String whose initial character is used by LIB$LOCC in the search.
The character-string argument contains the address of a descriptor
pointing to this string. Only the first character of
character-string is used, and its length is not checked.
source-string
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
String to be searched by LIB$LOCC. The source-string argument is
the address of a descriptor pointing to this character string.
LIB$LOOKUP_KEY
The Look Up Keyword In Table routine scans a table of keywords to
find one that matches the keyword or keyword abbreviation specified
by search-string.
Format:
LIB$LOOKUP_KEY search-string ,key-table-array [,key-value]
[,keyword-string] [,resultant-length]
Arguments:
search-string
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
String for which LIB$LOOKUP_KEY will search in the keyword table.
The search-string argument is the address of a descriptor pointing
to this string.
key-table-array
VMS usage: unspecified
type: unspecified
access: read only
mechanism: by reference, array reference
Keyword table. The key-table-array argument contains the address of
an array that is this keyword table.
key-value
VMS usage: longword_unsigned
type: longword (unsigned)
access: write only
mechanism: by reference
Value of the keyword found by LIB$LOOKUP_KEY. The key-value
argument contains the address of an unsigned longword that is this
keyword value. LIB$LOOKUP_KEY writes the address of this unsigned
longword into key-value.
keyword-string
VMS usage: char_string
type: character string
access: write only
mechanism: by descriptor
Full keyword match. The keyword-string argument contains the
address of a descriptor pointing to the keyword string.
LIB$LOOKUP_KEY writes the address of this descriptor into
keyword-string if the full keyword is matched.
resultant-length
VMS usage: word_unsigned
type: word (unsigned)
access: write only
mechanism: by reference
Number of characters in the keyword, independent of padding. The
resultant-length argument is the address of an unsigned word integer
that contains the number of characters in the keyword.
LIB$LOOKUP_KEY writes the address of this signed word integer into
resultant-length.
LIB$LOOKUP_TREE
The Look Up an Entry in a Balanced Binary Tree routine looks up an
entry in a balanced binary tree.
Format:
LIB$LOOKUP_TREE treehead ,symbol ,user-compare-routine ,new-node
Arguments:
treehead
VMS usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
Tree head for the binary tree. The treehead argument is the address
of an unsigned longword that is this tree head.
symbol
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
Key to be looked up in the binary tree. The symbol argument is the
address of a descriptor pointing to the symbol key.
user-compare-routine
VMS usage: procedure
type: procedure entry mask
access: function call (before return)
mechanism: by reference, procedure reference
User-supplied compare routine that LIB$LOOKUP_TREE calls to compare
a symbol with a node. The user-compare-routine argument is the
address of the entry mask to the compare routine. The value
returned by the compare routine indicates the relationship between
the symbol key and the current node.
new-node
VMS usage: address
type: longword (unsigned)
access: write only
mechanism: by reference
Location where the new symbol was found. The new-node argument is
the address of an unsigned longword that is the new node location.
LIB$LP_LINES
The Lines on Each Printer Page routine computes the default number
of lines on a printer page. This procedure can be used by
native-mode VMS utilities that produce listing files and do
pagination.
Format:
LIB$LP_LINES
NONE
LIB$MATCHC
The Match Characters and Return Relative Position routine searches a
source string for a specified substring and returns an index, which
is the relative position of the first occurrence of a substring in
the source string. LIB$MATCHC makes the VAX MATCHC instruction
available as a callable procedure.
Format:
LIB$MATCHC sub-string ,source-string
Arguments:
sub-string
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
Substring to be found. The sub-string argument is the address of a
descriptor pointing to this substring.
source-string
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
Source string to be searched by LIB$MATCHC. The source-string
argument is the address of a descriptor pointing to this source
string.
LIB$MATCH_COND
The Match Condition Values routine checks to see if a given
condition value matches a list of condition values that you supply.
Format:
LIB$MATCH_COND match-condition-value
,compare-condition-value ,...
Arguments:
match-condition-value
VMS usage: cond_value
type: longword (unsigned)
access: read only
mechanism: by reference
Condition value to be matched. The match-condition-value argument
is the address of an unsigned longword that contains this condition
value.
compare-condition-value
VMS usage: cond_value
type: longword (unsigned)
access: read only
mechanism: by reference
The condition value(s) to be compared to match-condition-value. The
compare-condition-value argument(s) are the address(es) of the
unsigned longword(s) that contain these condition value(s).
LIB$MOVC3
The Move Characters routine makes the VAX MOVC3 instruction
available as a callable procedure. The source item is moved to the
destination item. Overlap of the source and destination items does
not affect the result.
Format:
LIB$MOVC3 word-integer-length ,source ,destination
Arguments:
word-integer-length
VMS usage: word_unsigned
type: word (unsigned)
access: read only
mechanism: by reference
Number of bytes to be moved from source to destination by LIB$MOVC3.
The word-integer-length argument is the address of an unsigned word
which contains this number of bytes. The maximum transfer is 65,535
bytes.
source
VMS usage: unspecified
type: unspecified
access: read only
mechanism: by reference
Item to be moved. The source argument is the address of this item.
destination
VMS usage: unspecified
type: unspecified
access: write only
mechanism: by reference
Item into which source will be moved. The destination argument is
the address of this item.
LIB$MOVC5
The Move Characters with Fill routine makes the VAX MOVC5
instruction available as a callable procedure. The source item is
moved to the destination item. Overlap of the source and
destination items does not affect the result.
Format:
LIB$MOVC5 word-integer-source-length ,source ,fill
,word-integer-destination-length ,destination
Arguments:
word-integer-source-length
VMS usage: word_unsigned
type: word (unsigned)
access: read only
mechanism: by reference
Number of bytes in the source item. The word-integer-source-length
argument is the address of an unsigned word that contains this
number of bytes. The maximum length of source is 65,535 bytes.
source
VMS usage: unspecified
type: unspecified
access: read only
mechanism: by reference
Item to be moved by LIB$MOVC5. The source argument is the address
of this item. If word-integer-source-length is zero, indicating
that destination is to be entirely filled by the fill character,
then source is ignored by LIB$MOVC5.
fill
VMS usage: byte_signed
type: byte integer (signed)
access: read only
mechanism: by reference
Character used to pad source to the length of destination. The fill
argument is the address of a signed byte integer that contains this
fill character.
word-integer-destination-length
VMS usage: word_unsigned
type: word (unsigned)
access: read only
mechanism: by reference
Length of destination in bytes. The word-integer-destination-length
argument is the address of an unsigned word that contains this
number of bytes. The maximum value of
word-integer-destination-length is 65,535 bytes.
destination
VMS usage: unspecified
type: unspecified
access: write only
mechanism: by reference
Item into which source will be moved. The destination argument is
the address of this item.
LIB$MOVTC
The Move Translated Characters routine moves the source string,
character by character, to the destination string after translating
each character using the specified translation table. LIB$MOVTC
makes the VAX MOVTC instruction available as a callable procedure.
Format:
LIB$MOVTC source-string ,fill-character ,translation-table
,destination-string
Arguments:
source-string
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
Source string to be translated and moved by LIB$MOVTC. The
source-string argument is the address of a descriptor pointing to
this source string.
fill-character
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
Fill character used to pad source-string to the length of
destination-string. The fill-character argument is the address of a
descriptor pointing to a string. The first character of this string
is used as the fill character. The length of this string is not
checked and fill-character is not translated.
translation-table
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
Translation table used by LIB$MOVTC. The translation-table argument
is the address of a descriptor pointing to the translation table
string. The translation table string is assumed to be 256
characters long.
destination-string
VMS usage: char_string
type: character string
access: write only
mechanism: by descriptor
Destination string into which LIB$MOVTC writes the translated
source-string. The destination-string argument is the address of a
descriptor pointing to this destination string.
LIB$MOVTUC
The Move Translated Until Character routine moves the source string,
character by character, to the destination string after translating
each character using the specified translation table until the stop
character is encountered. LIB$MOVTUC makes the VAX MOVTUC
instruction available as a callable procedure.
Format:
LIB$MOVTUC source-string ,stop-character ,translation-table
,destination-string [,fill-character]
Arguments:
source-string
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
Source string to be translated and moved by LIB$MOVTUC. The
source-string argument is the address of a descriptor pointing to
this source string.
stop-character
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
Stop character that causes LIB$MOVTUC to stop translating the source
string. The stop-character argument is the address of a descriptor
pointing to a string. The first character of this string is used as
the stop character. The length of this string is not checked and
stop-character is not translated.
translation-table
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
Translation table used by LIB$MOVTUC. The translation-table
argument is the address of a descriptor pointing to the translation
table string. The translation table string is assumed to be 256
characters long.
destination-string
VMS usage: char_string
type: character string
access: write only
mechanism: by descriptor
Destination string into which LIB$MOVTUC writes the translated
source-string. The destination-string argument is the address of a
descriptor pointing to this destination string.
fill-character
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
Character used to pad source-string to the length of
destination-string. The fill-character argument is the address of a
descriptor pointing to a string. The first character of this string
is used as the fill character. The length of this string is not
checked and fill-character is not translated.
LIB$MULT_DELTA_TIME
The Multiply Delta Time by Scalar routine multiplies a delta time by
a longword integer scalar.
Format:
LIB$MULT_DELTA_TIME multiplier ,delta-time
Arguments:
multiplier
VMS usage: longword_signed
type: longword (signed)
access: read only
mechanism: by reference
The value by which LIB$MULT_DELTA_TIME multiplies the delta time.
The multiplier argument is the address of a signed longword
containing the integer scalar. If multiplier is negative, the
absolute value of multiplier is used.
delta-time
VMS usage: date_time
type: quadword (unsigned)
access: modify
mechanism: by reference
The delta time to be multiplied. The delta-time argument is the
address of an unsigned quadword containing the number to be
multiplied. Delta-time must be less than 10,000 days. After
LIB$MULT_DELTA_TIME performs the multiplication, the result is
returned to delta-time. (The original delta-time is overwritten.)
LIB$MULTF_DELTA_TIME
The Multiply Delta Time by an F-Floating Scalar routine multiplies a
delta time by an F-floating scalar.
Format:
LIB$MULTF_DELTA_TIME multiplier ,delta-time
Arguments:
multiplier
VMS usage: floating_point
type: F_floating
access: read only
mechanism: by reference
The value by which LIB$MULTF_DELTA_TIME multiplies the delta time.
The multiplier argument is the address of an F-floating value
containing the scalar. If multiplier is negative, the absolute
value of multiplier is used.
delta-time
VMS usage: date_time
type: quadword (unsigned)
access: modify
mechanism: by reference
The delta time to be multiplied. The delta-time argument is the
address of an unsigned quadword containing the number to be
multiplied. Delta-time must be less than 10,000 days. After
LIB$MULTF_DELTA_TIME performs the multiplication, the result is
returned to delta-time. (The original delta-time is overwritten.)
LIB$PAUSE
The Pause Program Execution routine suspends program execution and
returns control to the calling command level.
Format:
LIB$PAUSE
NONE
LIB$POLYD
The Evaluate Polynomials routine (D-floating point values) allows
higher-level language users to evaluate D-floating point value
polynomials.
Format:
LIB$POLYD polynomial-argument ,degree ,coefficient
,floating-point-result
Arguments:
polynomial-argument
VMS usage: floating_point
type: D_floating
access: read only
mechanism: by reference
Argument for the polynomial. The polynomial-argument argument is
the address of a floating-point number that contains this argument.
The polynomial-argument argument is a D_floating number.
degree
VMS usage: word_signed
type: word integer (signed)
access: read only
mechanism: by reference
Highest numbered non-zero coefficient to participate in the
evaluation. The degree argument is the address of a signed word
integer that contains this highest-numbered coefficient.
coefficient
VMS usage: floating_point
type: D_floating
access: read only
mechanism: by reference, array reference
Floating-point coefficients. The coefficient argument is the
address of an array of floating-point coefficients. The coefficient
of the highest-order term of the polynomial is the lowest-addressed
element in the array. The coefficient argument is an array of
D_floating numbers.
floating-point-result
VMS usage: floating_point
type: D_floating
access: write only
mechanism: by reference
Result of the calculation. The floating-point-result argument is
the address of a floating-point number that contains this result.
LIB$POLYD writes the address of floating-point-result into a
D_floating number.
LIB$POLYF
The Evaluate Polynomials routine (F-floating point values) allows
higher-level language users to evaluate F-floating point
polynomials.
Format:
LIB$POLYF polynomial-argument ,degree ,coefficient
,floating-point-result
Arguments:
polynomial-argument
VMS usage: floating_point
type: F_floating
access: read only
mechanism: by reference
Argument for the polynomial. The polynomial-argument argument is
the address of a floating-point number that contains this argument.
The polynomial-argument argument is an F_floating number.
degree
VMS usage: word_signed
type: word (signed)
access: read only
mechanism: by reference
Highest numbered nonzero coefficient to participate in the
evaluation. The degree argument is the address of a signed word
integer that contains this highest-numbered coefficient.
coefficient
VMS usage: floating_point
type: F_floating
access: read only
mechanism: by reference, array reference
Floating-point coefficients. The coefficient argument is the
address of an array of floating-point coefficients. The coefficient
of the highest-order term of the polynomial is the lowest-addressed
element in the array. The coefficient argument is an array of
F_floating numbers.
floating-point-result
VMS usage: floating_point
type: F_floating
access: write only
mechanism: by reference
Result of the calculation. The floating-point-result argument is
the address of a floating-point number that contains this result.
LIB$POLYF writes the address of floating-point-result into an
F_floating number.
LIB$POLYG
The Evaluate Polynomials routine (G-floating point values) allows
higher-level language users to evaluate G-floating point value
polynomials.
Format:
LIB$POLYG polynomial-argument ,degree ,coefficient
,floating-point-result
Arguments:
polynomial-argument
VMS usage: floating_point
type: G_floating
access: read only
mechanism: by reference
Argument for the polynomial. The polynomial-argument argument is
the address of a floating-point number that contains this argument.
The polynomial-argument argument is an G_floating number.
degree
VMS usage: word_signed
type: word integer (signed)
access: read only
mechanism: by reference
Highest numbered non-zero coefficient to participate in the
evaluation. The degree argument is the address of a signed word
integer that contains this highest-numbered coefficient.
coefficient
VMS usage: floating_point
type: G_floating
access: read only
mechanism: by reference, array reference
Floating-point coefficients. The coefficient argument is the
address of an array of floating-point coefficients. The coefficient
of the highest-order term of the polynomial is the lowest-addressed
element in the array. The coefficient argument is an array of
G_floating numbers.
floating-point-result
VMS usage: floating_point
type: G_floating
access: write only
mechanism: by reference
Result of the calculation. The floating-point-result argument is
the address of a floating-point number that contains this result.
LIB$POLYG writes the address of floating-point-result into an
G_floating number.
LIB$POLYH
The Evaluate Polynomials routine (H-floating point values) allows
higher-level language users to evaluate H-floating point value
polynomials.
Format:
LIB$POLYH polynomial-argument ,degree ,coefficient
,floating-point-result
Arguments:
polynomial-argument
VMS usage: floating_point
type: H_floating
access: read only
mechanism: by reference
Argument for the polynomial. The polynomial-argument argument is
the address of a floating-point number that contains this argument.
The polynomial-argument argument is an H_floating number.
degree
VMS usage: word_signed
type: word integer (signed)
access: read only
mechanism: by reference
Highest numbered non-zero coefficient to participate in the
evaluation. The degree argument is the address of a signed word
integer that contains this highest-numbered coefficient.
coefficient
VMS usage: floating_point
type: H_floating
access: read only
mechanism: by reference, array reference
Floating-point coefficients. The coefficient argument is the
address of an array of floating-point coefficients. The coefficient
of the highest-order term of the polynomial is the lowest-addressed
element in the array. The coefficient argument is an array of
H_floating numbers.
floating-point-result
VMS usage: floating_point
type: H_floating
access: write only
mechanism: by reference
Result of the calculation. The floating-point-result argument is
the address of a floating-point number that contains this result.
LIB$POLYH writes the address of floating-point-result into an
H_floating number.
LIB$PUT_COMMON
The Put String to Common routine copies the contents of a string
into the common area. The common area is an area of storage which
remains defined across multiple image activations in a process.
Optionally, LIB$PUT_COMMON returns the actual number of characters
copied. The maximum number of characters that can be copied is 252.
Format:
LIB$PUT_COMMON source-string [,resultant-length]
Arguments:
source-string
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
Source string to be copied to the common area by LIB$PUT_COMMON.
The source-string argument is the address of a descriptor pointing
to this source string.
resultant-length
VMS usage: word_unsigned
type: word (unsigned)
access: write only
mechanism: by reference
Number of characters copied by LIB$PUT_COMMON to the common area.
The resultant-length argument is the address of an unsigned word
integer that contains this number of characters. LIB$PUT_COMMON
writes this number into the resultant-length argument.
LIB$PUT_OUTPUT
The Put Line to SYS$OUTPUT routine writes a record to the current
controlling output device, specified by SYS$OUTPUT using the VAX RMS
$PUT service.
Format:
LIB$PUT_OUTPUT message-string
ARGUMENT
message-string
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
Message string written to the current controlling output device by
LIB$PUT_OUTPUT. The message-string argument is the address of a
descriptor pointing to this message string. VAX RMS handles all
formatting, so the message does not need to include such ASCII
formatting instructions as carriage return (CR).
LIB$RADIX_POINT
The Radix Point Symbol routine returns the system's radix point
symbol. This symbol is used inside a digit string to separate the
integer part from the fraction part. This routine works by
attempting to translate the logical name SYS$RADIX_POINT as a
process, group, or system logical name.
Format:
LIB$RADIX_POINT radix-point-string [,resultant-length]
Arguments:
radix-point-string
VMS usage: char_string
type: character string
access: write only
mechanism: by descriptor
Radix point string. The radix-point-string argument is the address
of a descriptor pointing to this radix point string.
resultant-length
VMS usage: word_unsigned
type: word (unsigned)
access: write only
mechanism: by reference
The number of characters written into radix-point-string, not
counting padding in the case of a fixed-length string. The
resultant-length argument is the address of an unsigned word that
contains this number.
LIB$REMQHI
The Remove Entry from Head of Queue routine removes an entry from
the head of the specified self-relative interlocked queue.
LIB$REMQHI makes the VAX REMQHI instruction available as a callable
procedure.
Format:
LIB$REMQHI header ,remque-address [,retry-count]
Arguments:
header
VMS usage: quadword_signed
type: quadword integer (signed)
access: modify
mechanism: by reference
Queue header specifying the queue from which entry will be removed.
The header argument contains the address of this signed aligned
quadword integer. Header must be initialized to zero before first
use of the queue; zero means an empty queue.
remque-address
VMS usage: address
type: longword (unsigned)
access: write only
mechanism: by reference
Address of the removed entry. The remque-address argument is the
address of an unsigned longword that contains this address. If the
queue was empty, remque-address is set to the address of the header.
retry-count
VMS usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
The number of times the operation is to be retried in case of
secondary-interlock failure of the queue instruction in a
processor-shared memory application. The retry-count argument is
the address of a longword that contains the retry count value. A
value of 1 causes no retries. The default value is 10.
LIB$REMQTI
The Remove Entry from Tail of Queue routine removes an entry from
the tail of the specified self-relative interlocked queue.
LIB$REMQTI makes the VAX REMQTI instruction available as a callable
procedure.
Format:
LIB$REMQTI header ,remque-address [,retry-count]
Arguments:
header
VMS usage: quadword_signed
type: quadword integer (signed)
access: modify
mechanism: by reference
Queue header specifying the queue from which the entry is to be
deleted. The header argument contains the address of this signed
aligned quadword integer. Header must be initialized to zero before
first use of the queue; zero means an empty queue.
remque-address
VMS usage: address
type: longword (unsigned)
access: write only
mechanism: by reference
Address of the removed entry. The remque-address argument is the
address of a longword that contains this address. If the queue was
empty, remque-address is set to the address of the header.
retry-count
VMS usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
The number of times the operation is to be retried in case of
secondary-interlock failure of the queue instruction in a
processor-shared memory application. The retry-count argument is
the address of a longword that is this retry count value. A value
of 1 causes no retries. The default value is 10.
LIB$RENAME_FILE
The Rename One or More Files routine changes the name(s) of one or
more files. The specification of the file(s) to be renamed may
include wildcards.
LIB$RENAME_FILE is similar in function to the DCL command RENAME.
Format:
LIB$RENAME_FILE old-filespec ,new-filespec [,default-filespec]
[,related-filespec] [,flags] [,user-success-routine]
[,user-error-routine] [,user-confirm-routine]
[,user-specified-argument] [,old-resultant-name]
[,new-resultant-name] [,file-scan-context]
Arguments:
old-filespec
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
File specification of the file(s) to be renamed. The old-filespec
argument is the address of a descriptor pointing to the old file
specification. The specification may include wildcards, in which
case each file which matches the specification will be renamed. The
string must not contain more than 255 characters. Any string class
is supported.
new-filespec
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
File specification for the new file name(s). The new-filespec
argument is the address of a descriptor pointing to the new file
specification.
default-filespec
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
Default file specification of the file(s) to be renamed. The
default-filespec argument is the address of a descriptor pointing to
the default file specification.
related-filespec
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
Related file specification of the file(s) to be renamed. The
related-filespec argument is the address of a descriptor pointing to
the related file specification. This is an optional argument; if
omitted, the default is the null string. Any string class is
supported.
flags
VMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Longword of flag bits designating optional behavior. The flags
argument is the address of an unsigned longword containing the flag
bits. This is an optional argument; if omitted, the default is that
all flags are clear.
user-success-routine
VMS usage: procedure
type: procedure entry mask
access: function call (before return)
mechanism: by value
User-supplied success routine that LIB$RENAME_FILE calls after each
successful rename. The user-success-routine argument is the address
of the entry mask to the success routine.
user-error-routine
VMS usage: procedure
type: procedure entry mask
access: function call (before return)
mechanism: by value
User-supplied error routine that LIB$RENAME_FILE calls when it
detects an error. The user-error-routine argument is the address of
the entry mask to the error routine. The value returned by the
error routine determines whether LIB$RENAME_FILE processes more
files.
user-confirm-routine
VMS usage: procedure
type: procedure entry mask
access: function call (before return)
mechanism: by value
User-supplied confirm routine that LIB$RENAME_FILE calls before it
renames a file. The user-confirm-routine argument is the address of
the entry mask to the confirm routine. The value returned by the
confirm routine determines whether or not LIB$RENAME_FILE renames
the file.
user-specified-argument
VMS usage: user_arg
type: unspecified
access: read only
mechanism: unspecified
Value that LIB$RENAME_FILE passes to the success, error and confirm
routines each time they are called. Whatever mechanism is used to
pass user-specified-argument to LIB$RENAME_FILE is also used to pass
it to the user-supplied routines. This is an optional argument; if
omitted, zero is passed by value.
old-resultant-name
VMS usage: char_string
type: character string
access: write only
mechanism: by descriptor
String into which LIB$RENAME_FILE copies the old resultant file
specification of the last file processed. This is an optional
argument. If present, it is used to store the file specification
passed to the user-supplied routines instead of a default class S,
type T string. Any string class is supported.
new-resultant-name
VMS usage: char_string
type: character string
access: write only
mechanism: by descriptor
String into which LIB$RENAME_FILE writes the new RMS resultant file
specification of the last file processed. The new-resultant-name
argument is the address of a descriptor pointing to the new name.
This is an optional argument. If present, it is used to store the
file specification passed to the user-supplied routines instead of a
class S, type T string. Any string class is supported.
file-scan-context
VMS usage: context
type: longword (unsigned)
access: modify
mechanism: by reference
Context for renaming a list of filespecs. The file-scan-context is
the address of a longword which contains this context. You must
initialize this longword to zero before the first of a series of
calls to LIB$RENAME_FILE. LIB$RENAME_FILE uses the file scan
context to retain the file context for multiple input files.
LIB$RESERVE_EF
The Reserve Event Flag routine allocates a local event flag number
specified by event-flag-number.
Format:
LIB$RESERVE_EF event-flag-number
argument
event-flag-number
VMS usage: ef_number
type: longword (unsigned)
access: read only
mechanism: by reference
Event flag number to be allocated by LIB$RESERVE_EF. The
event-flag-number argument contains the address of a signed longword
integer that is this event flag number.
LIB$RESET_VM_ZONE
The Reset Virtual Memory Zone routine frees all blocks of memory
that were previously allocated from the zone.
Format:
LIB$RESET_VM_ZONE zone-id
Arguments:
zone-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Zone identifier. The zone-id is the address of a longword that
contains the identifier of a zone created by a previous call to
LIB$CREATE_VM_ZONE or LIB$CREATE_USER_VM_ZONE.
LIB$REVERT
The Revert to the Handler of the Procedure Activator routine deletes
the condition handler established by LIB$ESTABLISH by clearing the
address pointing to the condition handler from the activated
procedure's stack frame.
Format:
LIB$REVERT
NONE
LIB$RUN_PROGRAM
The Run New Program routine causes the current program to stop
running and begins execution of another program.
Format:
LIB$RUN_PROGRAM program-name
Argument
program-name
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
File name of the program to be run in place of the current program.
The program-name argument contains the address of a descriptor
pointing to this file name string.
LIB$SCANC
The Scan for Characters and Return Relative Position routine is used
to find a specified set of characters in the source string.
LIB$SCANC makes the VAX SCANC instruction available as a callable
procedure.
Format:
LIB$SCANC source-string ,table-array ,byte-integer-mask
Arguments:
source-string
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
Source string used by LIB$SCANC to index into a table. The
source-string argument contains the address of a descriptor pointing
to this source string.
table-array
VMS usage: vector_mask_byte
type: byte (unsigned)
access: read only
mechanism: by reference, array reference
Table that LIB$SCANC indexes into and ANDs with the
byte-integer-mask byte. The table-array argument contains the
address of an unsigned byte array that is this table.
byte-integer-mask
VMS usage: mask_byte
type: byte (unsigned)
access: read only
mechanism: by reference
Mask that is ANDed with bytes in table-array. The byte-integer-mask
argument contains the address of an unsigned byte that is this mask.
LIB$SCOPY_DXDX
The Copy Source String Passed by Descriptor to Destination routine
copies a source string passed by descriptor to a destination string.
Format:
LIB$SCOPY_DXDX source-string ,destination-string
Arguments:
source-string
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
Source string to be copied to the destination string by
LIB$SCOPY_DXDX. The source-string argument contains the address of
a descriptor pointing to this source string. The descriptor class
can be unspecified, fixed-length, decimal string, array,
noncontiguous array, varying, or dynamic.
destination-string
VMS usage: char_string
type: character string
access: write only
mechanism: by descriptor
Destination string to which the source string is copied. The
destination-string argument contains the address of a descriptor
pointing to this destination string.
LIB$SCOPY_R_DX
The Copy Source String Passed by Reference to Destination String
routine copies a source string passed by reference to a destination
string.
Format:
LIB$SCOPY_R_DX word-integer-source-length
,source-string-address ,destination-string
Arguments:
word-integer-source-length
VMS usage: word_unsigned
type: word (unsigned)
access: read only
mechanism: by reference
Length of the source string. The word-integer-source-length
argument contains the address of an unsigned word that is this
length.
source-string-address
VMS usage: char_string
type: character string
access: read only
mechanism: by reference
Source string to be copied to the destination string by
LIB$SCOPY_R_DX. The source-string-address argument is the address
of this source string.
destination-string
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
Destination string to which the source string is copied. The
destination-string argument contains the address of a descriptor
pointing to this destination string.
LIB$SET_LOGICAL
The Set Logical Name routine requests the calling process's Command
Language Interpreter (CLI) to define or redefine a supervisor-mode
process logical name. It provides the same function as the DCL
DEFINE command.
Format:
LIB$SET_LOGICAL logical-name [,value-string] [,table]
[,attributes] [,item-list]
Either the item-list or value-string argument must be
specified. If both item-list and value-string are
specified, the value-string argument is ignored.
Arguments:
logical-name
VMS usage: logical_name
type: character string
access: read only
mechanism: by descriptor
Logical name to be defined or redefined. The logical-name argument
contains the address of a descriptor pointing to this logical name
string. The maximum length of a logical name is 255 characters.
value-string
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
Value to be given to the logical name. The value-string argument
contains the address of a descriptor pointing to this value string.
The maximum length of a logical name value is 255 characters.
table
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
Name of the table in which to create the logical name. The table
argument contains the address of a descriptor pointing to the
logical name table. If no table is specified, LNM$PROCESS is used
as the default.
attributes
VMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Logical name or translation attributes. The attributes argument is
the address of a longword bit mask that contains the logical name or
translation attributes.
item-list
VMS usage: item_list_3
type: unspecified
access: read only
mechanism: by reference, array reference
Item list describing the equivalence names for this logical name.
The item-list argument contains the address of an array that
contains this item list. If item-list is not specified, the logical
name will have only one value, as specified in the value-string
argument.
LIB$SET_SYMBOL
The Set Value of CLI Symbol routine requests the calling process's
Command Language Interpreter (CLI) to define or redefine a CLI
symbol.
Format:
LIB$SET_SYMBOL symbol ,value-string [,table-type-indicator]
Arguments:
symbol
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
Name of the symbol to be defined or modified by LIB$SET_SYMBOL. The
symbol argument is the address of a descriptor pointing to this
symbol string. If you redefine a previously defined CLI symbol, the
symbol value is modified to the new value that you provide.
value-string
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
Value to be given to the symbol. The value-string argument is the
address of a descriptor pointing to this value string.
table-type-indicator
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Indicator of the table which will contain the defined symbol. The
table-type-indicator argument is the address of a signed longword
integer that is this table indicator.
LIB$SFREE1_DD
The Free One Dynamic String routine returns one dynamic string area
to free storage.
Format:
LIB$SFREE1_DD descriptor-address
ARGUMENT
descriptor-address
VMS usage: quadword_unsigned
type: quadword (unsigned)
access: modify
mechanism: by reference
Dynamic descriptor specifying the area to be deallocated. The
descriptor-address argument is the address of an unsigned quadword
that is this descriptor. The descriptor is assumed to be dynamic
and its class field is not checked.
LIB$SFREEN_DD
The Free One or More Dynamic Strings routine returns one or more
dynamic strings to free storage.
Format:
LIB$SFREEN_DD number-of-descriptors ,first-descriptor-array
Arguments:
number-of-descriptors
VMS usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
Number of adjacent descriptors to be flagged by LIB$FREEN_DD as
having no allocated area (DSC$A_POINTER = 0 and DSC$W_LENGTH = 0).
The number-of-descriptors argument contains the address of an
unsigned longword that is this number. The deallocated area is
returned to free storage.
first-descriptor-array
VMS usage: vector_quadword_unsigned
type: quadword (unsigned)
access: modify
mechanism: by reference, array reference
First descriptor of an array of descriptors. The
first-descriptor-array argument contains the address of an unsigned
quadword that is this first descriptor. The descriptors are assumed
to be dynamic, and their class fields are not checked.
LIB$SGET1_DD
The Get One Dynamic String routine allocates dynamic virtual memory
to the string descriptor you specify.
Format:
LIB$SGET1_DD word-integer-length ,descriptor-part
Arguments:
word-integer-length
VMS usage: word_unsigned
type: word (unsigned)
access: read only
mechanism: by reference
Number of bytes of dynamic virtual memory to be allocated by
LIB$SGET1_DD. The word-integer-length argument is the address of an
unsigned word that contains this number. The amount of storage
allocated may be rounded up automatically. If the number of bytes
is zero, a small amount of space is allocated.
descriptor-part
VMS usage: quadword_unsigned
type: quadword (unsigned)
access: write only
mechanism: by reference
Descriptor of the dynamic string to which LIB$SGET1_DD will allocate
the dynamic virtual memory. The descriptor-part argument contains
the address of an unsigned quadword that is this descriptor.
LIB$SHOW_TIMER
The Show Accumulated Times and Counts routine returns times and
counts accumulated since the last call to LIB$INIT_TIMER and
displays them on SYS$OUTPUT. A user-supplied action routine may
change this default behavior.
Format:
LIB$SHOW_TIMER [handle-address] [,code] [,user-action-routine]
[,user-argument-value]
Arguments:
handle-address
VMS usage: address
type: longword (unsigned)
access: read only
mechanism: by reference
Block of storage containing the value returned by a previous call to
LIB$INIT_TIMER. The handle-address argument is the address of an
unsigned longword integer containing that value.
o If specified, the pointer must be the same value returned by a
previous call to LIB$INIT_TIMER.
o If omitted, LIB$SHOW_TIMER will use a block of memory allocated
by LIB$INIT_TIMER.
o If handle-address is omitted and LIB$INIT_TIMER has not been
called previously, the error LIB$_INVARG is returned.
LIB$INIT_TIMER must be called prior to a call to LIB$SHOW_TIMER.
code
VMS usage: longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Integer specifying the statistic you want; if it is omitted or zero,
all five statistics are returned on one line. The code argument is
the address of a signed longword integer containing the statistic
code.
user-action-routine
VMS usage: procedure
type: procedure entry mask
access: function call (before return)
mechanism: by value
User-supplied action routine called by LIB$SHOW_TIMER. The
user-action-routine argument is the address of the entry mask to
this routine. The default action of LIB$SHOW_TIMER is to write the
results to SYS$OUTPUT. An action routine is useful if you want to
write the results to a file, or in general, anywhere other than
SYS$OUTPUT.
user-argument-value
VMS usage: user_arg
type: unspecified
access: read only
mechanism: by value
A 32-bit value to be passed to the action routine without
interpretation. If omitted, LIB$SHOW_TIMER passes a zero by value
to the user routine.
LIB$SHOW_VM
The Show Virtual Memory Statistics routine returns the statistics
accumulated from calls to LIB$GET_VM/LIB$FREE_VM and
LIB$GET_VM_PAGE/LIB$FREE_VM_PAGE.
Format:
LIB$SHOW_VM [code] [,user-action-routine]
[,user-specified-argument]
Arguments:
code
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Code specifying any one of the statistics to be written to
SYS$OUTPUT or passed to an action routine for processing. The code
argument is the address of a signed longword integer containing the
statistic code. This is an optional argument. If the statistic
code is omitted or is zero, statistics for values 1, 2, and 3 are
returned on one line.
user-action-routine
VMS usage: procedure
type: procedure entry mask
access: function call (before return)
mechanism: by value
User-supplied action routine called by LIB$SHOW_VM. By default,
LIB$SHOW_VM returns statistics to SYS$OUTPUT. An action routine is
useful when you want to return statistics to a file or, in general,
to anyplace other than SYS$OUTPUT. The user-action-routine argument
is the address of the entry mask to the action routine. The routine
returns either a success or failure condition value, which will be
returned as the value of LIB$SHOW_VM.
user-specified-argument
VMS usage: user_arg
type: unspecified
access: read only
mechanism: unspecified
A 32-bit value to be passed directly to the action routine without
interpretation. That is, the contents of the argument list entry
user-specified-argument are copied to the argument list entry for
user-action-routine.
LIB$SHOW_VM_ZONE
The Return Information About a Zone routine returns formatted
information about the specified zone, detailing such information as
the zone's name, characteristics, and areas, and then passes the
information to the specified or default action routine.
Format:
LIB$SHOW_VM_ZONE zone-id [,detail-level] [,user-action-routine]
[,user-arg]
Arguments:
zone-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Zone identifier. The zone-id argument is the address of an unsigned
longword containing this identifier. Use zero to indicate the
default zone.
detail-level
VMS usage: longword_signed
type: longword (signed)
access: read only
mechanism: by reference
An identifier code specifying the level of detail required by the
user. The detail-level argument is the address of a signed longword
containing this code. The default is minimal information. The
following are valid values for detail-level:
0 zone-id and name
1 zone-id, name, algorithm, flags and size information
2 zone-id, name, algorithm, flags, size information,
cache information and area summary
3 zone-id, name, algorithm, flags, size information,
cache information, area summary and queue validation
user-action-routine
VMS usage: procedure
type: procedure entry mask
access: function call (before return)
mechanism: by value
Optional user-supplied action routine called by LIB$SHOW_VM_ZONE.
The user-action-routine argument is the address of the entry mask of
the action routine. By default, LIB$SHOW_VM_ZONE prints statistics
to SYS$OUTPUT via LIB$PUT_OUTPUT. An action routine is useful when
you want to return statistics to a file or, in general, to any
location other than SYS$OUTPUT. If user-action-routine fails,
LIB$SHOW_VM_ZONE terminates and returns a failure code. Success
codes are ignored.
user-arg
VMS usage: user_arg
type: unspecified
access: read only
mechanism: by reference
Optional 32-bit value to be passed directly to the action routine
without interpretation. That is, the contents of the argument list
entry user-arg are copied to the argument list entry for
user-action-routine.
LIB$SIGNAL
The Signal Exception Condition routine generates a signal that
indicates that an exception condition has occurred in your program.
If a condition handler does not take corrective action and the
condition is severe, then your program will exit.
Format:
LIB$SIGNAL condition-value1 [,number-of-arguments1]
[,FAO-argument1...] [,condition-value2]
[,number-of-arguments2] [,FAO-argument2...]
Only the condition-value1 argument must be specified;
other arguments are optional. The number-of-arguments1
argument, if specified, contains the number of FAO
arguments that will be associated with
condition-value1. The condition-value2 argument is
optional; it may be specified with or without the
number-of-arguments2 or FAO-argument2 arguments. The
number-of-arguments2 argument, if specified, contains
the number of FAO arguments that will be associated
with condition-value2. You may specify
condition-value3, condition-value4, condition-value5,
and so on, along with their corresponding
number-of-arguments and FAO arguments.
Arguments:
condition-value1
VMS usage: cond_value
type: longword (unsigned)
access: read only
mechanism: by value
VAX 32-bit condition value. The condition-value1 argument is an
unsigned longword that contains this condition value.
number-of-arguments1
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by value
Number of FAO arguments associated with the condition value. The
optional number-of-arguments1 argument is a signed longword integer
that contains this number. If omitted or specified as zero, no FAO
arguments follow.
FAO-argument1
VMS usage: varying_arg
type: unspecified
access: read only
mechanism: by value
Optional FAO (formatted ASCII output) argument that is associated
with the specified condition value.
condition-value2
VMS usage: cond_value
type: longword (unsigned)
access: read only
mechanism: by value
VAX 32-bit condition value. The optional condition-value2 argument
is an unsigned longword that contains this condition value.
number-of-arguments2
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by value
Number of FAO arguments associated with the condition value. The
optional number-of-arguments2 argument is a signed longword integer
that contains this number. If omitted or specified as zero, no FAO
arguments follow.
FAO-argument2
VMS usage: varying_arg
type: unspecified
access: read only
mechanism: by value
Optional FAO (formatted ASCII output) argument that is associated
with the specified condition value.
LIB$SIG_TO_RET
The Signal Converted to a Return Status routine converts any
signaled condition value to a value returned as a function. The
signaled condition is returned to the caller of the user procedure
that established the handler that is calling LIB$SIG_TO_RET. This
routine may be established as or called from a condition handler.
Format:
LIB$SIG_TO_RET signal-arguments ,mechanism-arguments
Arguments:
signal-arguments
VMS usage: vector_longword_unsigned
type: unspecified
access: read only
mechanism: by reference, array reference
Signal argument vector. The signal-arguments argument contains the
address of an array that is this signal argument vector stack.
mechanism-arguments
VMS usage: vector_longword_unsigned
type: unspecified
access: read only
mechanism: by reference, array reference
Mechanism arguments vector. The mechanism-arguments argument
contains the address of an array that is this mechanism arguments
vector stack.
LIB$SIG_TO_STOP
The Convert a Signaled Condition to a Signaled Stop routine converts
a signaled condition to a signaled condition that cannot be
continued.
Format:
LIB$SIG_TO_STOP signal-arguments ,mechanism-arguments
Arguments:
signal-arguments
VMS usage: vector_longword_unsigned
type: unspecified
access: modify
mechanism: by reference, array reference
Signal argument vector. The signal-arguments argument contains the
address of an array of unsigned longwords that is this signal
argument vector stack.
mechanism-arguments
VMS usage: vector_longword_unsigned
type: unspecified
access: read only
mechanism: by reference, array reference
Mechanism argument vector. The mechanism-arguments argument
contains the address of an array of longwords that is this mechanism
argument vector stack.
LIB$SIM_TRAP
The Simulate Floating Trap routine converts floating faults to
floating traps. It can be enabled as a condition handler or can be
called by one.
Format:
LIB$SIM_TRAP signal-arguments ,mechanism-arguments
Arguments:
signal-arguments
VMS usage: vector_longword_unsigned
type: unspecified
access: modify
mechanism: by reference, array reference
Signal argument vector. The signal-arguments argument contains the
address of an array that is this signal argument vector stack.
mechanism-arguments
VMS usage: vector_longword_unsigned
type: unspecified
access: read only
mechanism: by reference, array reference
Mechanism argument vector. The mechanism-arguments argument
contains the address of an array that is this mechanism argument
vector stack.
LIB$SKPC
The Skip Equal Characters routine compares each character of a given
string with a given character and returns the relative position of
the first nonequal character as an index. LIB$SKPC makes the VAX
SKPC instruction available as a callable procedure.
Format:
LIB$SKPC character-string ,source-string
Arguments:
character-string
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
String whose initial character is to be used by LIB$SKPC in the
comparison. The character-string argument contains the address of a
descriptor pointing to this string. Only the first character of
character-string is used, and the length of character-string is not
checked.
source-string
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
String to be searched by LIB$SKPC. The source-string argument
contains the address of a descriptor pointing to this string.
LIB$SPANC
The Skip Selected Characters routine is used to skip a specified set
of characters in the source string. LIB$SPANC makes the VAX SPANC
instruction available as a callable procedure.
Format:
LIB$SPANC source-string ,table-array ,byte-integer-mask
Arguments:
source-string
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
Source string used by LIB$SPANC to index into table-array. The
source-string argument contains the address of a descriptor pointing
to this source string.
table-array
VMS usage: vector_mask_byte
type: byte (unsigned)
access: read only
mechanism: by reference, array reference
Table that LIB$SPANC indexes into and ANDs with the
byte-integer-mask byte. The table-array argument contains the
address of an unsigned byte array that is this table.
byte-integer-mask
VMS usage: mask_byte
type: byte (unsigned)
access: read only
mechanism: by reference
Mask that is ANDed with bytes in table-array. The byte-integer-mask
argument contains the address of an unsigned byte that is this mask.
LIB$SPAWN
The Spawn Subprocess routine requests the command language
interpreter (CLI) of the calling process to spawn a subprocess for
executing CLI commands. LIB$SPAWN provides the same function as the
DCL SPAWN command.
Format:
LIB$SPAWN [command-string] [,input-file] [,output-file] [,flags]
[,process-name] [,process-id] [,completion-status-address]
[,byte-integer-event-flag-num] [,AST-address]
[,varying-AST-argument] [,prompt-string] [,cli] [,table]
Arguments:
command-string
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
CLI command to be executed by the spawned subprocess. The
command-string argument is the address of a descriptor pointing to
this CLI command string. If omitted, commands are taken from the
file specified by input-file.
input-file
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
Equivalence name to be associated with the logical name SYS$INPUT in
the logical name table for the subprocess. The input-file argument
is the address of a descriptor pointing to this equivalence string.
If omitted, the default is the caller's SYS$INPUT.
output-file
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
Equivalence name to be associated with the logical names SYS$OUTPUT
and SYS$ERROR in the logical name table for the subprocess. The
output-file argument is the address of a descriptor pointing to this
equivalence string. If omitted, the default is the caller's
SYS$OUTPUT.
flags
VMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Flag bits that designate optional behavior. The flags argument is
the address of an unsigned longword that contains these flag bits.
By default, all flags are clear.
process-name
VMS usage: process_name
type: character string
access: read only
mechanism: by descriptor
Name defined for the subprocess. The process-name argument is the
address of a descriptor pointing to this name string. If omitted, a
unique process name will be generated. If you supply a name and it
is not unique, LIB$SPAWN will return the condition value
SS$_DUPLNAM.
process-id
VMS usage: process_id
type: longword (unsigned)
access: write only
mechanism: by reference
Process identification of the spawned subprocess. The process-id
argument is the address of an unsigned longword that contains this
process identification value.
completion-status-address
VMS usage: address
type: longword (unsigned)
access: write only
mechanism: by value
The final completion status of the subprocess. The
completion-status-address argument is the address of an unsigned
longword. LIB$SPAWN writes the address of the final completion
status of the subprocess into completion-status-address.
byte-integer-event-flag-num
VMS usage: byte_unsigned
type: byte (unsigned)
access: read only
mechanism: by reference
The number of a local event flag to be set when the spawned
subprocess completes. The byte-integer-event-flag-num argument is
the address of an unsigned byte that contains this event flag
number. If omitted, no event flag is set.
AST-address
VMS usage: procedure
type: procedure entry mask
access: call without stack unwinding
mechanism: by value
Entry mask of a procedure to be called by means of an AST when the
subprocess completes. The AST-address argument is the address of
this procedure entry mask.
varying-AST-argument
VMS usage: user_arg
type: unspecified
access: read only
mechanism: by value
A value to be passed to the AST procedure. Typically, the
varying-AST-argument argument is the address of a block of storage
the AST procedure will use.
prompt-string
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
Prompt string to use in the subprocess. The prompt-string argument
is the address of a descriptor pointing to this prompt string. If
omitted, the subprocess will use the same prompt string that the
parent process uses.
cli
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
File specification for the command language interpreter (CLI) to be
run in the subprocess. The cli argument is the address of this file
specification string's descriptor. The CLI specified must reside in
SYS$SYSTEM with a file type of EXE, and it must be installed. No
directory or file type may be specified.
table
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
File specification for the command tables to be used by the spawned
process. The table argument is the address of this file
specification string's descriptor. The table specified must reside
in SYS$SHARE with a file type of EXE, and it must be installed. If
omitted, the subprocess will use the same table as the parent
process.
LIB$STAT_TIMER
The Statistics, Return Accumulated Times and Counts routine returns
to its caller one of five available statistics accumulated since the
last call to LIB$INIT_TIMER. Unlike LIB$SHOW_TIMER, which formats
the values for output, LIB$STAT_TIMER returns the value as an
unsigned longword or quadword.
Format:
LIB$STAT_TIMER code ,value-argument [,handle-address]
Arguments:
code
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Code which specifies the statistic to be returned. The code
argument contains the address of a signed longword integer that is
this code. It must be an integer from 1 to 5.
value-argument
VMS usage: user_arg
type: unspecified
access: write only
mechanism: by reference
The statistic returned by LIB$STAT_TIMER. The value-argument
argument contains the address of a longword or quadword that is this
statistic. All statistics are longword integers except elapsed
time, which is a quadword.
handle-address
VMS usage: address
type: longword (unsigned)
access: read only
mechanism: by reference
Pointer to a block of storage. The optional handle-address argument
contains the address of an unsigned longword that is this pointer.
LIB$STAT_VM
The Return Virtual Memory Statistics routine returns to its caller
one of six statistics available from calls to LIB$GET_VM/LIB$FREE_VM
and LIB$GET_VM_PAGE/LIB$FREE_VM_PAGE. Unlike LIB$SHOW_VM, which
formats the values for output and displays them on SYS$OUTPUT,
LIB$STAT_VM returns the statistic in the value-argument argument.
Only one of the statistics is returned by each call to LIB$STAT_VM.
Format:
LIB$STAT_VM code ,value-argument
Arguments:
code
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Code specifying which statistic is to be returned. The code
argument contains the address of a signed longword integer that is
this code.
Code Statistic
1 Number of successful calls to LIB$GET_VM
2 Number of successful calls to LIB$FREE_VM
3 Number of bytes allocated by LIB$GET_VM but not yet
deallocated by LIB$FREE_VM
5 Number of calls to LIB$GET_VM_PAGE
6 Number of calls to LIB$FREE_VM_PAGE
7 Number of pages allocated by LIB$GET_VM_PAGE but not
yet deallocated by LIB$FREE_VM_PAGE
value-argument
VMS usage: user_arg
type: unspecified
access: write only
mechanism: by reference
Value of the statistic returned by LIB$STAT_VM. The value-argument
argument contains the address of a signed longword integer that is
this value.
LIB$STOP
The Stop Execution and Signal the Condition routine generates a
signal that indicates that an exception condition has occurred in
your program. Exception conditions signaled by LIB$STOP cannot be
continued from the point of the signal.
Format:
LIB$STOP condition-value1 [,number-of-arguments1]
[,FAO-argument1...] [,condition-value2]
[,number-of-arguments2] [,FAO-argument2...]
Only the condition-value1 argument must be specified;
other arguments are optional. The number-of-arguments1
argument, if specified, contains the number of FAO
arguments that will be associated with
condition-value1. The condition-value2 argument is
optional; it may be specified with or without the
number-of-arguments2 or FAO-argument2 arguments. The
number-of-arguments2 argument, if specified, contains
the number of FAO arguments that will be associated
with condition-value2. You may specify
condition-value3, condition-value4, condition-value5,
and so on, along with their corresponding
number-of-arguments and FAO arguments.
Arguments:
condition-value1
VMS usage: cond_value
type: longword (unsigned)
access: read only
mechanism: by value
VAX 32-bit condition value. The condition-value1 argument is an
unsigned longword that contains this condition value.
number-of-arguments1
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by value
Number of FAO arguments associated with the condition value. The
optional number-of-arguments1 argument is a signed longword integer
that contains this number. If omitted or specified as zero, no FAO
arguments follow.
FAO-argument1
VMS usage: varying_arg
type: unspecified
access: read only
mechanism: unspecified
Optional FAO (formatted ASCII output) argument that is associated
with the specified condition value.
condition-value2
VMS usage: cond_value
type: longword (unsigned)
access: read only
mechanism: by value
VAX 32-bit condition value. The optional condition-value2 argument
is an unsigned longword that contains this condition value.
number-of-arguments2
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by value
Optional FAO argument associated with the condition value. The
number-of-arguments2 argument is a signed longword integer that
contains this number. If omitted or specified as zero, no FAO
arguments follow.
FAO-argument2
VMS usage: varying_arg
type: unspecified
access: read only
mechanism: unspecified
FAO (formatted ASCII output) argument that is associated with the
specified condition value.
LIB$SUB_TIMES
The Subtract Two Quadword Times routine subtracts two VMS internal
time format times.
Format:
LIB$SUB_TIMES time1 ,time2 ,resultant-time
Arguments:
time1
VMS usage: date_time
type: quadword (unsigned)
access: read only
mechanism: by reference
First time, from which LIB$SUB_TIMES subtracts the second time. The
time1 argument is the address of an unsigned quadword containing
this number. Time1 must represent a later time or a longer time
interval than time2. Time1 may be either absolute time or delta
time as long as time2 is of the same type. If time1 and time2 are
of different types, time1 must be the absolute time.
time2
VMS usage: date_time
type: quadword (unsigned)
access: read only
mechanism: by reference
Second time, which LIB$SUB_TIMES subtracts from the first time. The
time2 argument is the address of an unsigned quadword containing
this number. Time2 must represent an earlier time or a shorter time
interval than time1. Time2 may be either absolute time or delta
time as long as time1 is of the same type. If time2 and time1 are
of different types, time2 must be the delta time.
resultant-time
VMS usage: date_time
type: quadword (unsigned)
access: write only
mechanism: by reference
The result of subtracting time2 from time1. The resultant-time
argument is the address of an unsigned quadword containing the
result. If both time1 and time2 are delta times, then
resultant-time is a delta time. If both time1 and time2 are
absolute times, then resultant-time is a delta time. If time1 is an
absolute time and time2 is a delta time, then resultant-time is an
absolute time.
LIB$SUBX
The Multiple-Precision Binary Subtraction routine performs
subtraction on signed two's complement integers of arbitrary length.
Format:
LIB$SUBX minuend-array ,subtrahend-array ,difference-array
[,array-length]
Arguments:
minuend-array
VMS usage: vector_longword_signed
type: unspecified
access: read only
mechanism: by reference, array reference
Minuend; a multiple-precision, signed two's complement integer. The
minuend-array argument is the address of an array of signed longword
integers that contains the minuend.
subtrahend-array
VMS usage: vector_longword_signed
type: unspecified
access: read only
mechanism: by reference, array reference
Subtrahend; a multiple-precision, signed two's complement integer.
The subtrahend-array argument is the address of an array of signed
longword integers that contains the subtrahend.
difference-array
VMS usage: vector_longword_signed
type: unspecified
access: write only
mechanism: by reference, array reference
Difference; a multiple-precision, signed two's complement integer
result. The difference-array argument is the address of an array of
signed longword integers that contains the difference.
array-length
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Length in longwords of the arrays to be operated on by LIB$SUBX.
The array-length argument contains the address of a signed longword
integer that is this length. Array-length must not be negative.
The default length is 2.
LIB$SYS_ASCTIM
The Invoke $ASCTIM to Convert Binary Time to ASCII String routine
calls the system service $ASCTIM to convert a binary date and time
value, returning the ASCII string using the semantics of the
caller's string.
Format:
LIB$SYS_ASCTIM [resultant-length] ,time-string [,user-time]
[,flags]
Arguments:
resultant-length
VMS usage: word_unsigned
type: word (unsigned)
access: write only
mechanism: by reference
Number of bytes written into time-string, not counting padding in
the case of a fixed-length string. The resultant-length argument
contains the address of an unsigned word integer that is this
number.
time-string
VMS usage: time_name
type: character string
access: write only
mechanism: by descriptor
Destination string into which LIB$SYS_ASCTIM writes the ASCII time
string. The time-string argument contains the address of a
descriptor pointing to the destination string.
user-time
VMS usage: date_time
type: quadword (unsigned)
access: read only
mechanism: by reference
Value that LIB$SYS_ASCTIM converts to ASCII string form. The
user-time argument contains the address of a signed quadword integer
that is this value.
flags
VMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Conversion indicator specifying which date and time fields
LIB$SYS_ASCTIM should return. The flags argument is the address of
an unsigned bit mask that contains this conversion indicator.
LIB$SYS_FAO
The Invoke $FAO System Service to Format Output routine calls $FAO,
returning a string in the semantics you provide. If called with
other than a fixed-length string for output, the length of the
resultant string is limited to 256 bytes and truncation will occur.
Format:
LIB$SYS_FAO character-string [,resultant-length]
,resultant-string [,directive-argument ,...]
Arguments:
character-string
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
ASCII control string, consisting of the fixed text of the output
string and FAO directives. The character-string argument contains
the address of a descriptor pointing to this control string.
resultant-length
VMS usage: word_unsigned
type: word (unsigned)
access: write only
mechanism: by reference
Length of the output string. The resultant-length argument contains
the address of an unsigned word integer that is this length.
resultant-string
VMS usage: char_string
type: character string
access: write only
mechanism: by descriptor
Fully formatted output string returned by LIB$SYS_FAO. The
resultant-string argument contains the address of a descriptor
pointing to this output string.
directive-argument(s)
VMS usage: varying_arg
type: unspecified
access: read only
mechanism: unspecified
Directive argument(s) contained in longwords. Depending on the
directive, a directive-argument argument can be a value to be
converted, the address of the string to be inserted, or a length or
argument count. The passing mechanism for each of these arguments
should be the one expected by the $FAO system service.
LIB$SYS_FAOL
The Invoke $FAOL System Service to Format Output routine calls the
system service routine $FAOL, returning the string in the semantics
you provide. If called with other than a fixed-length string for
output, the length of the resultant string is limited to 256 bytes
and truncation will occur.
Format:
LIB$SYS_FAOL character-string ,[resultant-length]
,resultant-string ,directive-argument-address ,...
Arguments:
character-string
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
ASCII control string, consisting of the fixed text of the output
string and FAO directives. The character-string argument contains
the address of a descriptor pointing to this control string.
resultant-length
VMS usage: word_unsigned
type: word (unsigned)
access: write only
mechanism: by reference
Length of the output string. The resultant-length argument contains
the address of an unsigned word integer that is this length.
resultant-string
VMS usage: char_string
type: character string
access: write only
mechanism: by descriptor
Fully formatted output string returned by LIB$SYS_FAOL. The
resultant-string argument contains the address of a descriptor
pointing to this output string.
directive-argument-address
VMS usage: address
type: longword (unsigned)
access: read only
mechanism: unspecified
Directive argument(s). The directive-argument-address arguments are
contained in an array of unsigned longword directive arguments.
Depending on the directive, a directive-argument-address argument
can be a value to be converted, the address of the string to be
inserted, or a length or argument count. The passing mechanism for
each of these arguments should be the one expected by the $FAOL
system service.
LIB$SYS_GETMSG
The Invoke $GETMSG System Service to Get Message Text routine calls
the System Service $GETMSG and returns a message string into
destination-string using the semantics of the caller's string.
Format:
LIB$SYS_GETMSG message-id ,[message-length] ,destination-string
[,flags] [,unsigned-resultant-array]
Arguments:
message-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Message identification to be retrieved by LIB$SYS_GETMSG. The
message-id argument contains the address of an unsigned longword
integer that is this message identification.
message-length
VMS usage: word_unsigned
type: word integer (unsigned)
access: write only
mechanism: by reference
Number of characters written into destination-string, not counting
padding in the case of a fixed-length string. The message-length
argument contains the address of an unsigned word integer that is
this number.
destination-string
VMS usage: char_string
type: character string
access: write only
mechanism: by descriptor
Destination string. The destination-string argument contains the
address of a descriptor pointing to this destination string.
LIB$SYS_GETMSG writes the message that has been returned by $GETMSG
into destination-string.
flags
VMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Four flag bits for message content. The flags argument is the
address of an unsigned longword that contains these flag bits. The
default value is a longword with bits zero through 3 set to 1. The
flags argument is passed to LIB$SYS_GETMSG by reference and changed
to value for use by $GETMSG.
unsigned-resultant-array
VMS usage: unspecified
type: unspecified
access: write only
mechanism: by reference, array reference
A 4-byte array to receive message-specific information. The
unsigned-resultant-array argument contains the address of this
array.
LIB$TPARSE
The Table-Driven Finite State Parser routine is a general-purpose,
table-driven parser implemented as a finite-state automaton, with
extensions that make it suitable for a wide range of applications.
LIB$TPARSE parses a string and returns a message indicating whether
or not the input string is valid.
Format:
LIB$TPARSE argument-block ,state-table ,key-table
Arguments:
argument-block
VMS usage: address
type: longword (unsigned)
access: modify
mechanism: by reference
LIB$TPARSE argument block. The argument-block argument contains the
address of this argument block.
state-table
VMS usage: address
type: unspecified
access: read only
mechanism: by reference
Starting state in the state table. The state-table argument is the
address of this starting state.
key-table
VMS usage: address
type: unspecified
access: read only
mechanism: by reference
Keyword table. The key-table argument is the address of this
keyword table.
LIB$TRA_ASC_EBC
The Translate ASCII to EBCDIC routine translates an ASCII string to
an EBCDIC string.
Format:
LIB$TRA_ASC_EBC source-string ,byte-integer-dest-string
Arguments:
source-string
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
Source string (ASCII) to be translated by LIB$TRA_ASC_EBC . The
source-string argument contains the address of a descriptor pointing
to this source string.
byte-integer-dest-string
VMS usage: char_string
type: character string
access: write only
mechanism: by descriptor
Destination string (EBCDIC). The byte-integer-dest-string argument
contains the address of a descriptor pointing to this destination
string.
LIB$TRA_EBC_ASC
The Translate EBCDIC to ASCII routine translates an EBCDIC string to
an ASCII string.
Format:
LIB$TRA_EBC_ASC byte-integer-source-string ,destination-string
Arguments:
byte-integer-source-string
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
String (EBCDIC) to be translated by LIB$TRA_EBC_ASC. The
byte-integer-source-string argument contains the address of a
descriptor pointing to this source string.
destination-string
VMS usage: char_string
type: character string
access: write only
mechanism: by descriptor
Destination string (ASCII). The destination-string argument
contains the address of the descriptor of this destination string.
LIB$TRAVERSE_TREE
The Traverse a Balanced Binary Tree routine calls an action routine
for each node in a binary tree.
Format:
LIB$TRAVERSE_TREE treehead ,user-action-routine
[,user-data-address]
Arguments:
treehead
VMS usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
Tree head of the binary tree. The treehead argument is the address
of an unsigned longword that is the tree head in the binary tree
traversal.
user-action-routine
VMS usage: procedure
type: procedure entry mask
access: function call (before return)
mechanism: by value
User-supplied action routine called by LIB$TRAVERSE_TREE for each
node in the tree. The user-action-routine argument is the address
of the entry mask to the action routine.
user-data-address
VMS usage: user_arg
type: unspecified
access: read only
mechanism: by reference
User data that LIB$TRAVERSE_TREE passes to your action routine. The
user-data-address argument contains the address of this user data.
This is an optional argument; the default value is zero.
LIB$TRIM_FILESPEC
The Fit Long File Specification into Fixed Field routine takes a
file specification, such as an RMS resultant name string, and
shortens it (if necessary) so that it fits into a field of fixed
width.
Format:
LIB$TRIM_FILESPEC old-filespec ,new-filespec
[,word-integer-width] [,resultant-length]
Arguments:
old-filespec
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
File specification to be trimmed. The old-filespec argument
contains the address of a descriptor pointing to this file
specification string.
new-filespec
VMS usage: char_string
type: character string
access: write only
mechanism: by descriptor
Trimmed file specification. The new-filespec argument contains the
address of a descriptor pointing to this trimmed file specification
string. LIB$TRIM_FILESPEC writes the trimmed file specification
into new-filespec.
word-integer-width
VMS usage: word_unsigned
type: word (unsigned)
access: read only
mechanism: by reference
Maximum field width desired. The word-integer-width argument is the
address of an unsigned word that contains this maximum field width.
resultant-length
VMS usage: word_unsigned
type: word (unsigned)
access: write only
mechanism: by reference
Length of the trimmed file specification, not including any blank
padding or truncated characters. The resultant-length argument is
the address of an unsigned word that contains this length. This is
an optional argument.
LIB$VERIFY_VM_ZONE
The Verify a Zone routine performs verification of a zone.
Format:
LIB$VERIFY_VM_ZONE zone-id
Arguments:
zone-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Zone identifier of the zone to be verified. The zone-id argument is
the address of an unsigned longword that contains this zone
identifier. A value of zero indicates the default zone.
LIB$WAIT
The Wait a Specified Period of Time routine places the current
process into hibernation for the number of seconds specified in its
argument.
Format:
LIB$WAIT seconds
ARGUMENT
seconds
VMS usage: floating_point
type: F_floating
access: read only
mechanism: by reference
The number of seconds to wait. The seconds argument contains the
address of an F_floating number that is this number.
MTH$
Additional information available:
MTH$CCOSMTH$CEXPMTH$CLOGMTH$CMPLXMTH$CONJG
MTH$CSINMTH$CSQRTMTH$HACOSMTH$HACOSD
MTH$HASINMTH$HASINDMTH$HATANMTH$HATAND
MTH$HATAN2MTH$HATAND2MTH$HATANHMTH$HCOS
MTH$HCOSDMTH$HCOSHMTH$HEXPMTH$HLOGMTH$HLOG2
MTH$HLOG10MTH$HSINMTH$HSINDMTH$HSINH
MTH$HSQRTMTH$HTANMTH$HTANDMTH$HTANH
MTH$RANDOMMTH$UMAXMTH$UMIN
BLAS1$VIxAMAXBLAS1$VxASUMBLAS1$VxAXPYBLAS1$VxCOPY
BLAS1$VxDOTxBLAS1$VxNRM2BLAS1$VxROTBLAS1$VxROTG
BLAS1$VxSCALBLAS1$VxSWAPMTH$xACOSMTH$xACOSD
MTH$xASINMTH$xASINDMTH$xATANMTH$xATAND
MTH$xATAN2MTH$xATAND2MTH$xATANHMTH$CxABS
MTH$CxCOSMTH$CxEXPMTH$CxLOGMTH$xCMPLX
MTH$xCONJGMTH$xCOSMTH$xCOSDMTH$xCOSH
MTH$CxSINMTH$CxSQRTMTH$CVT x xMTH$CVT xA xA
MTH$xEXPMTH$xIMAGMTH$xLOGMTH$xLOG2MTH$xLOG10
MTH$xREALMTH$xSINMTH$xSINCOSMTH$xSINCOSD
MTH$xSINDMTH$xSINHMTH$xSQRTMTH$xTANMTH$xTAND
MTH$xTANHMTH$VxFOLRy MA V15MTH$VxFOLRy z V8MTH$VxFOLRLy MA V5
MTH$VxFOLRLy z V2MTH$VxFOLRLy z V2
BLAS1$VIxAMAX
The Obtain the Index of the First Element of a Vector Having
the Largest Absolute Value routines find the index of the first
occurrence of a vector element having the maximum absolute value.
Format
BLAS1$VISAMAX n ,x ,incx
BLAS1$VIDAMAX n ,x ,incx
BLAS1$VIGAMAX n ,x ,incx
BLAS1$VICAMAX n ,x ,incx
BLAS1$VIZAMAX n ,x ,incx
BLAS1$VIWAMAX n ,x ,incx
Use BLAS1$VISAMAX for single-precision real operations. Use
BLAS1$VIDAMAX for double-precision real (D-floating) operations
and BLAS1$VIGAMAX for double-precision real (G-floating)
operations.
Use BLAS1$VICAMAX for single-precision complex operations.
Use BLAS1$VIZAMAX for double-precision complex (D-floating)
operations and BLAS1$VIWAMAX for double-precision complex (G-
floating) operations.
Arguments
n
VMS Usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Number of elements in vector x. The n argument is the address of a
signed longword integer containing the number of elements. If you
specify a negative value or 0 for n, 0 is returned.
x
VMS Usage: floating_point or complex_number
type: F_floating, D_floating, G_floating real or F_floating,
D_floating, G_floating complex
access: read only
mechanism: by reference, array reference
Array containing the elements to be accessed. All elements of
array x are accessed only if the increment argument of x, called
incx, is 1. The x argument is the address of a floating-point or
floating-point complex number that is this array. This argument is
an array of length at least
1+(n-1)*|incx|
where:
n number of vector elements specified in n
incx increment argument for the array x specified in
incx
If n is less than or equal to 0, then imax is 0.
incx
VMS Usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Increment argument for the array x. The incx argument is the
address of a signed longword integer containing the increment
argument. If incx is greater than or equal to 0, then x is
referenced forward in array x; that is, xi is referenced as
x(1+(i-1)*incx)
where:
x array specified in x
i element of the vector x
incx increment argument for the array x specified in incx
If you specify a negative value for incx, it is interpreted as the
absolute value of incx.
BLAS1$VxASUM
The Obtain the Sum of the Absolute Values of the Elements of a
Vector routines determine the sum of the absolute values of the
elements of the n-element vector x.
Format
BLAS1$VSASUM n ,x ,incx
BLAS1$VDASUM n ,x ,incx
BLAS1$VGASUM n ,x ,incx
BLAS1$VSCASUM n ,x ,incx
BLAS1$VDZASUM n ,x ,incx
BLAS1$VGWASUM n ,x ,incx
Use BLAS1$VSASUM for single-precision real operations. Use
BLAS1$VDASUM for double-precision real (D-floating) operations
and BLAS1$VGASUM for double-precision real (G-floating)
operations.
Use BLAS1$VSCASUM for single-precision complex operations.
Use BLAS1$VDZASUM for double-precision complex (D-floating)
operations and BLAS1$VGWASUM for double-precision complex (G-
floating) operations.
Arguments
n
VMS Usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Number of elements in vector x to be added. The n argument is
the address of a signed longword integer containing the number of
elements.
x
VMS Usage: floating_point or complex_number
type: F_floating, D_floating, G_floating real or F_floating,
D_floating, G_floating complex
access: read only
mechanism: by reference, array reference
Array containing the elements to be accessed. All elements of
array x are accessed only if the increment argument of x, called
incx, is 1. The x argument is the address of a floating-point or
floating-point complex number that is this array. This argument is
an array of length at least
1+(n-1)*|incx|
where:
n number of vector elements specified in n
incx increment argument for the array x specified in incx
If n is less than or equal to 0, then sum is 0.0.
incx
VMS Usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Increment argument for the array x. The incx argument is the
address of a signed longword integer containing the increment
argument. If incx is greater than or equal to 0, then x is
referenced forward in array x; that is, xi is referenced in
x(1+(i-1)*incx)
where:
x array specified in x
i element of the vector x
incx increment argument for the array x specified in incx
If you specify a negative value for incx, it is interpreted as the
absolute value of incx.
BLAS1$VxAXPY
The Multiply a Vector by a Scalar and Add a Vector routines
compute ax+y, where a is a scalar number and x and y are n-element
vectors.
Format
BLAS1$VSAXPY n ,a ,x ,incx ,y ,incy
BLAS1$VDAXPY n ,a ,x ,incx ,y ,incy
BLAS1$VGAXPY n ,a ,x ,incx ,y ,incy
BLAS1$VCAXPY n ,a ,x ,incx ,y ,incy
BLAS1$VZAXPY n ,a ,x ,incx ,y ,incy
BLAS1$VWAXPY n ,a ,x ,incx ,y ,incy
Use BLAS1$VSAXPY for single-precision real operations. Use
BLAS1$VDAXPY for double-precision real (D-floating) operations
and BLAS1$VGAXPY for double-precision real (G-floating)
operations.
Use BLAS1$VCAXPY for single-precision complex operations.
Use BLAS1$VZAXPY for double-precision complex (D-floating)
operations and BLAS1$VWAXPY for double-precision complex (G-
floating) operations.
Arguments
n
VMS Usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Number of elements in vectors x and y. The n argument is the
address of a signed longword integer containing the number of
elements. If n is less than or equal to 0, then y is unchanged.
a
VMS Usage: floating_point or complex_number
type: F_floating, D_floating, G_floating real or F_floating,
D_floating, G_floating complex
access: read only
mechanism: by reference, array reference
Scalar multiplier for the array x. The a argument is the address
of a floating-point or floating-point complex number that is this
multiplier. If a equals 0, then y is unchanged. If a shares a
memory location with any element of the vector y, results are
unpredictable. Specify the same data type for arguments a, x, and
y.
x
VMS Usage: floating_point or complex_number
type: F_floating, D_floating, G_floating real or F_floating,
D_floating, G_floating complex
access: read only
mechanism: by reference, array reference
Array containing the elements to be accessed. All elements of
array x are accessed only if the increment argument of x, called
incx, is 1. The x argument is the address of a floating-point or
floating-point complex number that is this array. The length of
this array is at least
1+(n-1)*|incx|
where:
n number of vector elements specified in n
incx increment argument for the array x specified in
incx
If any element of x shares a memory location with an element of y,
the results are unpredictable.
incx
VMS Usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Increment argument for the array x. The incx argument is the
address of a signed longword integer containing the increment
argument. If incx is greater than or equal to 0, then x is
referenced forward in array x; that is, xi is referenced in
x(1+(i-1)*incx)
where:
x array specified in x
i element of the vector x
incx increment argument for the array x specified in incx
If incx is less than 0, then x is referenced backward in array x;
that is, xi is referenced in
x(1+(n-i)*|incx|)
where:
x array specified in x
n number of vector elements specified in n
i element of the vector x
incx increment argument for the array x specified in incx
y
VMS Usage: floating_point or complex_number
type: F_floating, D_floating, G_floating real or F_floating,
D_floating, G_floating complex
access: modify
mechanism: by reference, array reference
On entry, array containing the elements to be accessed. All
elements of array y are accessed only if the increment argument of
y, called incy, is 1. The y argument is the address of a floating-
point or floating-point complex number that is this array. The
length of this array is at least
1+(n-1)*|incy|
where:
n number of vector elements specified in n
incy increment argument for the array y specified in incy
If n is less than or equal to 0, then y is unchanged. If any
element of x shares a memory location with an element of y, the
results are unpredictable.
On exit, y contains an array of length at least
1+(n-1)*|incy|
where:
n number of vector elements specified in n
incy increment argument for the array y specified in incy
After the call to BLAS1$VxAXPY, yi is set equal to
yi +a*x i.
where:
y the vector y
i element of the vector x or y
a scalar multiplier for the vector x specified in a
x the vector x
incy
VMS Usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Increment argument for the array y. The incy argument is the
address of a signed longword integer containing the increment
argument. If incy is greater than or equal to 0, then y is
referenced forward in array y; that is, yi is referenced in
y(1+(i-1)*incy)
where:
y array specified in y
i element of the vector y
incy increment argument for the array y specified in incy
If incy is less than 0, then y is referenced backward in array y;
that is, yi is referenced in
y(1+(n-i)*|incy|)
where:
y array specified in y
n number of vector elements specified in n
i element of the vector y
incy increment argument for the array y specified in incy
BLAS1$VxCOPY
The Copy a Vector routines copy n elements of the vector x to the
vector y.
Format
BLAS1$VSCOPY n ,x ,incx ,y ,incy
BLAS1$VDCOPY n ,x ,incx ,y ,incy
BLAS1$VCCOPY n ,x ,incx ,y ,incy
BLAS1$VZCOPY n ,x ,incx ,y ,incy
Use BLAS1$VSCOPY for single-precision real operations and
BLAS1$VDCOPY for double-precision real (D or G) operations.
Use BLAS1$VCCOPY for single-precision complex operations and
BLAS1$VZCOPY for double-precision complex (D or G) operations.
Arguments
n
VMS Usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Number of elements in vector x to be copied. The n argument is
the address of a signed longword integer containing the number of
elements in vector x. If n is less than or equal to 0, then y is
unchanged.
x
VMS Usage: floating_point or complex_number
type: F_floating, D_floating, G_floating real or F_floating,
D_floating, G_floating complex
access: read only
mechanism: by reference, array reference
Array containing the elements to be accessed. All elements of
array x are accessed only if the increment argument of x, called
incx, is 1. The x argument is the address of a floating-point or
floating-point complex number that is this array. This argument is
an array of length at least
1+(n-1)*|incx|
where:
n number of vector elements specified in n
incx increment argument for the array x specified in incx
incx
VMS Usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Increment argument for the array x. The incx argument is the
address of a signed longword integer containing the increment
argument. If incx is greater than or equal to 0, then x is
referenced forward in array x; that is, xi is referenced in
x(1+(i-1)*incx)
where:
x array specified in x
i element of the vector x
incx increment argument for the array x specified in incx
If incx is less than 0, then x is referenced backward in array x;
that is, xi is referenced in
x(1+(n-i)*|incx|)
where:
x array specified in x
n number of vector elements specified in n
i element of the vector x
incx increment argument for the array x specified in incx
y
VMS Usage: floating_point or complex_number
type: F_floating, D_floating, G_floating real or F_floating,
D_floating, G_floating complex
access: write only
mechanism: by reference, array reference
Array that receives the copied elements. All elements of array y
receive the copied elements only if the increment argument of y,
called incy, is 1. The y argument is the address of a floating-
point or floating-point complex number that is this array. This
argument is an array of length at least
1+(n-1)*|incy|
where:
n number of vector elements specified in n
incy increment argument for the array y specified in incy
If n is less than or equal to 0, then y is unchanged. If incx is
equal to 0, then each yi is set to x. If incy is equal to 0, then
yi is set to the last referenced element of x. If any element of
x shares a memory location with an element of y, the results are
unpredictable. (See the Description section for a special case
that does not cause unpredictable results when the same memory
location is shared by input and output.)
incy
VMS Usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Increment argument for the array y. The incy argument is the
address of a signed longword integer containing the increment
argument. If incy is greater than or equal to 0, then y is
referenced forward in array y; that is, yi is referenced in
y(1+(i-1)*incy)
where:
y array specified in y
i element of the vector y
If incy is less than 0, then y is referenced backward in array y;
that is, yi is referenced in
y(1+(n-i)*|incy|)
where:
y array specified in y
n number of vector elements specified in n
i element of the vector y
incy increment argument for the array y specified in incy
BLAS1$VxDOTx
The Obtain the Inner Product of Two Vectors routines return the
dot product of two n-element vectors, x and y.
Format
BLAS1$VSDOT n ,x ,incx ,y ,incy
BLAS1$VDDOT n ,x ,incx ,y ,incy
BLAS1$VGDOT n ,x ,incx ,y ,incy
BLAS1$VCDOTU n ,x ,incx ,y ,incy
BLAS1$VCDOTC n ,x ,incx ,y ,incy
BLAS1$VZDOTU n ,x ,incx ,y ,incy
BLAS1$VWDOTU n ,x ,incx ,y ,incy
BLAS1$VZDOTC n ,x ,incx ,y ,incy
BLAS1$VWDOTC n ,x ,incx ,y ,incy
Use BLAS1$VSDOT to obtain the inner product of two single-
precision real vectors.
Use BLAS1$VDDOT to obtain the inner product of two double-
precision (D-floating) real vectors. Use BLAS1$VGDOT to obtain
the inner product of two double-precision (G-floating) real
vectors.
Use BLAS1$VCDOTU to obtain the inner product of two single-
precision complex vectors (unconjugated).
Use BLAS1$VCDOTC to obtain the inner product of two single-
precision complex vectors (conjugated).
Use BLAS1$VZDOTU to obtain the inner product of two double-
precision (D-floating) complex vectors (unconjugated). Use
BLAS1$VWDOTU to obtain the inner product of two double-
precision (G-floating) complex vectors (unconjugated).
Use BLAS1$VZDOTC to obtain the inner product of two double-
precision (D-floating) complex vectors (conjugated). Use
BLAS1$VWDOTC to obtain the inner product of two double-
precision (G-floating) complex vectors (conjugated).
Arguments
n
VMS Usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Number of elements in vector x. The n argument is the address of a
signed longword integer containing the number of elements. If you
specify a value for n that is less than or equal to 0, then the
value of dotpr is 0.0.
x
VMS Usage: floating_point or complex_number
type: F_floating, D_floating, G_floating real or F_floating,
D_floating, G_floating complex
access: read only
mechanism: by reference, array reference
Array containing the elements to be accessed. All elements of
array x are accessed only if the increment argument of x, called
incx, is 1. The x argument is the address of a floating-point or
floating-point complex number that is this array. This argument is
an array of length at least
1+(n-1)*|incx|
where:
n number of vector elements specified in n
incx increment argument for the array x specified in incx
incx
VMS Usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Increment argument for the array x. The incx argument is the
address of a signed longword integer containing the increment
argument. If incx is greater than 0, then x is referenced forward
in array x; that is, xi is referenced in
x(1+(i-1)*incx)
where:
x array specified in x
i element of the vector x
incx increment argument for the array x specified in incx
If incx is less than 0, then x is referenced backward in array x;
that is, xi is referenced in
x(1+(n-i)*|incx|)
where:
x array specified in x
n number of vector elements specified in n
i element of the vector x
incx increment argument for the array x specified in incx
y
VMS Usage: floating_point or complex_number
type: F_floating, D_floating, G_floating real or F_floating,
D_floating, G_floating complex
access: read only
mechanism: by reference, array reference
Array containing the elements to be accessed. All elements of
array y are accessed only if the increment argument of y, called
incy, is 1. The y argument is the address of a floating-point or
floating-point complex number that is this array. This argument is
an array of length at least
1+(n-1)*|incy|
where:
n number of vector elements specified in n
incy increment argument for the array y specified in incy
incy
VMS Usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Increment argument for the array y. The incy argument is the
address of a signed longword integer containing the increment
argument. If incy is greater than or equal to 0, then y is
referenced forward in array y; that is, yi is referenced in
y(1+(i-1)*incy)
where:
y array specified in y
i element of the vector y
incy increment argument for the array y specified in incy
If incy is less than 0, then y is referenced backward in array y;
that is, yi is referenced in
y(1+(n-i)*|incy|)
where:
y array specified in y
n number of vector elements specified in n
i element of the vector y
incy increment argument for the array y specified in incy
BLAS1$VxNRM2
The Obtain the Euclidean Norm of a Vector routines obtain the
Euclidean norm of an n-element vector x, expressed as follows:
#_2___2________2
|x +x +...+x
# 1 2 n
Format
BLAS1$VSNRM2 n ,x ,incx
BLAS1$VDNRM2 n ,x ,incx
BLAS1$VGNRM2 n ,x ,incx
BLAS1$VSCNRM2 n ,x ,incx
BLAS1$VDZNRM2 n ,x ,incx
BLAS1$VGWNRM2 n ,x ,incx
Use BLAS1$VSNRM2 for single-precision real operations. Use
BLAS1$VDNRM2 for double-precision real (D-floating) operations
and BLAS1$VGNRM2 for double-precision real (G-floating)
operations.
Use BLAS1$VSCNRM2 for single-precision complex operations.
Use BLAS1$VDZNRM2 for double-precision complex (D-floating)
operations and BLAS1$VGWNRM2 for double-precision complex (G-
floating) operations.
Arguments
n
VMS Usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Number of elements in vector x to be processed. The n argument is
the address of a signed longword integer containing the number of
elements.
x
VMS Usage: floating_point or complex_number
type: F_floating, D_floating, G_floating real or F_floating,
D_floating, G_floating complex
access: read only
mechanism: by reference, array reference
Array containing the elements to be accessed. All elements of
array x are accessed only if the increment argument of x, called
incx, is 1. The x argument is the address of a floating-point or
floating-point complex number that is this array. This argument is
an array of length at least
1+(n-1)*|incx|
where:
n number of vector elements specified in n
incx increment argument for the array x specified in incx
If n is less than or equal to 0, then e_norm is 0.0.
incx
VMS Usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Increment argument for the array x. The incx argument is the
address of a signed longword integer containing the increment
argument. If incx is greater than or equal to 0, then x is
referenced forward in array x; that is, xi is referenced in
x(1+(i-1)*incx)
where:
x array specified in x
i element of the vector x
incx increment argument for the array x specified in incx
If you specify a negative value for incx, it is interpreted as the
absolute value of incx.
BLAS1$VxROT
The Apply a Givens Plane Rotation routines apply a Givens plane
rotation to a pair of n-element vectors x and y.
Format
BLAS1$VSROT n ,x ,incx ,y ,incy ,c ,s
BLAS1$VDROT n ,x ,incx ,y ,incy ,c ,s
BLAS1$VGROT n ,x ,incx ,y ,incy ,c ,s
BLAS1$VCSROT n ,x ,incx ,y ,incy ,c ,s
BLAS1$VZDROT n ,x ,incx ,y ,incy ,c ,s
BLAS1$VWGROT n ,x ,incx ,y ,incy ,c ,s
Use BLAS1$VSROT for single-precision real operations. Use
BLAS1$VDROT for double-precision real (D-floating) operations
and BLAS1$VGROT for double-precision real (G-floating)
operations.
Use BLAS1$VCSROT for single-precision complex operations.
Use BLAS1$VZDROT for double-precision complex (D-floating)
operations and BLAS1$VWGROT for double-precision complex
(G-floating) operations. BLAS1$VCSROT, BLAS1$VZDROT, and
BLAS1$VWGROT are real rotations applied to a complex vector.
Arguments
n
VMS Usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Number of elements in vector x to be rotated. The n argument is
the address of a signed longword integer containing the number of
elements to be rotated. If n is less than or equal to 0, then x
and y are unchanged.
x
VMS Usage: floating_point or complex_number
type: F_floating, D_floating, G_floating real or F_floating,
D_floating, G_floating complex
access: modify
mechanism: by reference, array reference
Array containing the elements to be accessed. All elements of
array x are accessed only if the increment argument of x, called
incx, is 1. The x argument is the address of a floating-point or
floating-point complex number that is this array. On entry, this
argument is an array of length at least
1+(n-1)*|incx|
where:
n number of vector elements specified in n
incx increment argument for the array x specified in incx
If n is less than or equal to 0, then x and y are unchanged. If
c equals 1.0 and s equals 0, then x and y are unchanged. If any
element of x shares a memory location with an element of y, then
the results are unpredictable.
On exit, x contains the rotated vector x, as follows:
xi = c*xi +s*y i
where:
x array x specified in x
y array y specified in y
i i = 1,2,...,n
c rotation element generated by the BLAS1$VxROTG routines
s rotation element generated by the BLAS1$VxROTG routines
incx
VMS Usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Increment argument for the array x. The incx argument is the
address of a signed longword integer containing the increment
argument. If incx is greater than or equal to 0, then x is
referenced forward in array x; that is, xi is referenced in
x(1+(i-1)*incx)
where:
x array specified in x
i element of the vector x
incx increment argument for the array x specified in incx
If incx is less than 0, then x is referenced backward in array x;
that is, xi is referenced in
x(1+(n-i)*|incx|)
where:
x array specified in x
n number of vector elements specified in n
i element of the vector x
incx increment argument for the array x specified in incx
y
VMS Usage: floating_point or complex_number
type: F_floating, D_floating, G_floating real or F_floating,
D_floating, G_floating complex
access: modify
mechanism: by reference, array reference
Array containing the elements to be accessed. All elements of
array y are accessed only if the increment argument of y, called
incy, is 1. The y argument is the address of a floating-point or
floating-point complex number that is this array. On entry, this
argument is an array of length at least
1+(n-1)*|incx|
where:
n number of vector elements specified in n
incx increment argument for the array x specified in incx
If n is less than or equal to 0, then x and y are unchanged. If
c equals 1.0 and s equals 0, then x and y are unchanged. If any
element of x shares a memory location with an element of y, then
the results are unpredictable.
On exit, y contains the rotated vector y, as follows:
yi = -s*xi +c*y i
where:
x array x specified in x
y array y specified in y
i i = 1,2,...,n
c real rotation element (can be generated by the BLAS1$VxROTG
routines)
s complex rotation element (can be generated by the
BLAS1$VxROTG routines)
incy
VMS Usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Increment argument for the array y. The incy argument is the
address of a signed longword integer containing the increment
argument. If incy is greater than or equal to 0, then y is
referenced forward in array y; that is, yi is referenced in
y(1+(i-1)*incy)
where:
y array specified in y
i element of the vector y
incy increment argument for the array y specified in incy
If incy is less than 0, then y is referenced backward in array y;
that is, yi is referenced in
y(1+(n-i)*|incy|)
where:
y array specified in y
n number of vector elements specified in n
i element of the vector y
incy increment argument for the array y specified in incy
c
VMS Usage: floating_point
type: F_floating, D_floating, or G_floating real
D_floating, G_floating complex
access: read only
mechanism: by reference
First rotation element, which can be interpreted as the cosine
of the angle of rotation. The c argument is the address of a
floating-point or floating-point complex number that is this
vector element. The c argument is the first rotation element
generated by the BLAS1$VxROTG routines.
s
VMS Usage: floating_point or complex_number
type: F_floating, D_floating, G_floating real or F_floating,
D_floating, G_floating complex
access: read only
mechanism: by reference
Second rotation element, which can be interpreted as the sine
of the angle of rotation. The s argument is the address of a
floating-point or floating-point complex number that is this
vector element. The s argument is the second rotation element
generated by the BLAS1$VxROTG routines.
Specify the same data type for arguments s and c.
BLAS1$VxROTG
The Generate the Elements for a Givens Plane Rotation routines
construct a Givens plane rotation that eliminates the second
element of a two-element vector.
Format
BLAS1$VSROTG a ,b ,c ,s
BLAS1$VDROTG a ,b ,c ,s
BLAS1$VGROTG a ,b ,c ,s
BLAS1$VCROTG a ,b ,c ,s
BLAS1$VZROTG a ,b ,c ,s
BLAS1$VWROTG a ,b ,c ,s
Use BLAS1$VSROTG for single-precision real operations. Use
BLAS1$VDROTG for double-precision real (D-floating) operations
and BLAS1$VGROTG for double-precision real (G-floating)
operations.
Use BLAS1$VCROTG for single-precision complex operations.
Use BLAS1$VZROTG for double-precision complex (D-floating)
operations and BLAS1$VWROTG for double-precision complex (G-
floating) operations.
Arguments
a
VMS Usage: floating_point or complex_number
type: F_floating, D_floating, G_floating real or F_floating,
D_floating, G_floating complex
access: modify
mechanism: by reference
On entry, first element of the input vector. On exit, rotated
element r. The a argument is the address of a floating-point or
floating-point complex number that is this vector element.
b
VMS Usage: floating_point or complex_number
type: F_floating, D_floating, G_floating real or F_floating,
D_floating, G_floating complex
access: modify
mechanism: by reference
On entry, second element of the input vector. On exit from
BLAS1$VSROTG, BLAS1$VDROTG, and BLAS1$VGROTG, reconstruction
element z. (See the Description section for more information
about z.) The b argument is the address of a floating-point or
floating-point complex number that is this vector element.
c
VMS Usage: floating_point
type: F_floating, D_floating, or G_floating real
D_floating, G_floating complex
access: write only
mechanism: by reference
First rotation element, which can be interpreted as the cosine
of the angle of rotation. The c argument is the address of a
floating-point or floating-point complex number that is this
vector element.
s
VMS Usage: floating_point or complex_number
type: F_floating, D_floating, G_floating real or F_floating,
D_floating, G_floating complex
access: write only
mechanism: by reference
Second rotation element, which can be interpreted as the sine
of the angle of rotation. The s argument is the address of a
floating-point or floating-point complex number that is this
vector element.
BLAS1$VxSCAL
The Scale the Elements of a Vector routines compute a * x where a
is a scalar number and x is an n-element vector.
Format
BLAS1$VSSCAL n ,a ,x ,incx
BLAS1$VDSCAL n ,a ,x ,incx
BLAS1$VGSCAL n ,a ,x ,incx
BLAS1$VCSCAL n ,a ,x ,incx
BLAS1$VCSSCAL n ,a ,x ,incx
BLAS1$VZSCAL n ,a ,x ,incx
BLAS1$VWSCAL n ,a ,x ,incx
BLAS1$VZDSCAL n ,a ,x ,incx
BLAS1$VWGSCAL n ,a ,x ,incx
Use BLAS1$VSSCAL to scale a real single-precision vector by a
real single-precision scalar.
Use BLAS1$VDSCAL to scale a real double-precision (D-floating)
vector by a real double-precision (D-floating) scalar. Use
BLAS1$VGSCAL to scale a real double-precision (G-floating)
vector by a real double-precision (G-floating) scalar.
Use BLAS1$VCSCAL to scale a complex single-precision vector by
a complex single-precision scalar. Use BLAS1$VCSSCAL to scale
a complex single-precision vector by a real single-precision
scalar.
Use BLAS1$VZSCAL to scale a complex double-precision (D-
floating) vector by a complex double-precision (D-floating)
scalar. Use BLAS1$VWSCAL to scale a complex double-precision
(G-floating) vector by a complex double-precision (G-floating)
scalar. Use BLAS1$VZDSCAL to scale a complex double-precision
(D-floating) vector by a real double-precision (D-floating)
scalar. Use BLAS1$VWGSCAL to scale a complex double-precision
(G-floating) vector by a real double-precision (G-floating)
scalar.
Arguments
n
VMS Usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Number of elements in vector x to be scaled. The n argument is
the address of a signed longword integer containing the number of
elements to be scaled. If you specify a value for n that is less
than or equal to 0, then x is unchanged.
a
VMS Usage: floating_point or complex_number
type: F_floating, D_floating, G_floating real or F_floating,
D_floating, G_floating complex
access: read only
mechanism: by reference
Scalar multiplier for the elements of vector x. The a argument is
the address of a floating-point or floating-point complex number
that is this multiplier.
If you specify 1.0 for a, then x is unchanged.
x
VMS Usage: floating_point or complex_number
type: F_floating, D_floating, G_floating real or F_floating,
D_floating, G_floating complex
access: modify
mechanism: by reference, array reference
Array containing the elements to be accessed. All elements of
array x are accessed only if the increment argument of x, called
incx, is 1. The x argument is the address of a floating-point or
floating-point complex number that is this array. On entry, this
argument is an array of length at least
1+(n-1)*|incx|
where:
n number of vector elements specified in n
incx increment argument for the array x specified in incx
On exit, x is an array of length at least
1+(n-1)*|incx|
where:
n number of vector elements specified in n
incx increment argument for the array x specified in incx
After the call to BLAS1$VxSCAL, xi is replaced by a * i . If a
shares a memory location with any element of the vector x, results
are unpredictable.
incx
VMS Usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Increment argument for the array x. The incx argument is the
address of a signed longword integer containing the increment
argument. If incx is greater than 0, then x is referenced forward
in array x; that is, xi is referenced in
x(1+(i-1)*incx)
where:
x array specified in x
i element of the vector x
incx increment argument for the array x specified in incx
If you specify a negative value for incx, it is interpreted as
the absolute value of incx. If incx equals 0, the results are
unpredictable.
BLAS1$VxSWAP
The Swap the Elements of Two Vectors routines swap n elements of
the vector x with the vector y.
Format
BLAS1$VSSWAP n ,x ,incx ,y ,incy
BLAS1$VDSWAP n ,x ,incx ,y ,incy
BLAS1$VCSWAP n ,x ,incx ,y ,incy
BLAS1$VZSWAP n ,x ,incx ,y ,incy
Use BLAS1$VSSWAP for single-precision real operations and
BLAS1$VDSWAP for double-precision real (D or G) operations.
Use BLAS1$VCSWAP for single-precision complex operations and
BLAS1$VZSWAP for double-precision complex (D or G) operations.
Arguments
n
VMS Usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Number of elements in vector x to be swapped. The n argument is
the address of a signed longword integer containing the number of
elements to be swapped.
x
VMS Usage: floating_point or complex_number
type: F_floating, D_floating, G_floating real or F_floating,
D_floating, G_floating complex
access: modify
mechanism: by reference, array reference
Array containing the elements to be accessed. All elements of
array x are accessed only if the increment argument of x, called
incx, is 1. The x argument is the address of a floating-point or
floating-point complex number that is this array. On entry, this
argument is an array of length at least
1+(n-1)*|incx|
where:
n number of vector elements specified in n
incx increment argument for the array x specified in incx
If n is less than or equal to 0, then x and y are unchanged. If
any element of x shares a memory location with an element of y,
the results are unpredictable.
On exit, x is an array of length at least
1+(n-1)*|incx|
where:
n number of vector elements specified in n
incx increment argument for the array x specified in incx
After the call to BLAS1$VxSWAP, the arrays specified by x and y
are interchanged.
incx
VMS Usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Increment argument for the array x. The incx argument is the
address of a signed longword integer containing the increment
argument. If incx is greater than or equal to 0, then x is
referenced forward in array x; that is, xi is referenced in
x(1+(i-1)*incx)
where:
x array specified in x
i element of the vector x
incx increment argument for the array x specified in incx
If incx is less than 0, then x is referenced backward in array x;
that is, xi is referenced in
x(1+(n-i)*|incx|)
where:
x array specified in x
n number of vector elements specified in n
i element of the vector x
incx increment argument for the array x specified in incx
y
VMS Usage: floating_point or complex_number
type: F_floating, D_floating, G_floating real or F_floating,
D_floating, G_floating complex
access: modify
mechanism: by reference, array reference
Array containing the elements to be accessed. All elements of
array y are accessed only if the increment argument of y, called
incy, is 1. The y argument is the address of a floating-point or
floating-point complex number that is this array. On entry, this
argument is an array of length at least
1+(n-1)*|incy|
where:
n number of vector elements specified in n
incy increment argument for the array y specified in incy
If n is less than or equal to 0, then x and y are unchanged. If
any element of x shares a memory location with an element of y,
the results are unpredictable.
On exit, y is an array of length at least
1+(n-1)*|incy|
where:
n number of vector elements specified in n
incy increment argument for the array x specified in incy
After the call to BLAS1$VxSWAP, the arrays specified by x and y
are interchanged.
incy
VMS Usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Increment argument for the array y. The incy argument is the
address of a signed longword integer containing the increment
argument. If incy is greater than or equal to 0, then y is
referenced forward in array y; that is, yi is referenced in
y(1+(i-1)*incy)
where:
y array specified in y
i element of the vector y
incy increment argument for the array y specified in incy
If incy is less than 0, then y is referenced backward in array y;
that is, yi is referenced in
y(1+(n-i)*|incy|)
where:
y array specified in y
n number of vector elements specified in n
i element of the vector y
incy increment argument for the array y specified in incy
MTH$xACOS
Given the cosine of an angle, the Arc Cosine of Angle Expressed in
Radians routine returns that angle (in radians).
Format:
MTH$ACOS cosine
MTH$DACOS cosine
MTH$GACOS cosine
Each of the above three formats accepts as input one
of the floating-point types.
Arguments:
cosine
VMS usage: floating_point
type: F_floating, D_floating, G_floating
access: read only
mechanism: by reference
The cosine of the angle whose value (in radians) is to be returned.
The cosine argument is the address of a floating-point number that
is this cosine. The absolute value of cosine must be less than or
equal to 1. For MTH$ACOS, cosine specifies an F_floating number.
For MTH$DACOS, cosine specifies a D_floating number. For MTH$GACOS,
cosine specifies a G_floating number.
MTH$xACOSD
Given the cosine of an angle, the Arc Cosine of Angle Expressed in
Degrees routine returns that angle (in degrees).
Format:
MTH$ACOSD cosine
MTH$DACOSD cosine
MTH$GACOSD cosine
Each of the above formats accepts as input one of
the floating-point types.
Arguments:
cosine
VMS usage: floating_point
type: F_floating, G_floating, D_floating
access: read only
mechanism: by reference
Cosine of the angle whose value (in degrees) is to be returned. The
cosine argument is the address of a floating-point number that is
this cosine. The absolute value of cosine must be less than or
equal to 1. For MTH$ACOSD, cosine specifies an F_floating number.
For MTH$DACOSD, cosine specifies a D_floating number. For
MTH$GACOSD, cosine specifies a G_floating number.
MTH$xASIN
Given the sine of an angle, the Arc Sine in Radians routine returns
that angle (in radians).
Format:
MTH$ASIN sine
MTH$DASIN sine
MTH$GASIN sine
Each of the above formats accepts as input one of
the floating-point types.
Arguments:
sine
VMS usage: floating_point
type: F_floating, D_floating, G_floating
access: read only
mechanism: by reference
The sine of the angle whose value (in radians) is to be returned.
The sine argument is the address of a floating-point number that is
this sine. The absolute value of sine must be less than or equal to
1. For MTH$ASIN, sine specifies an F_floating number. For
MTH$DASIN, sine specifies a D_floating number. For MTH$GASIN, sine
specifies a G_floating number.
MTH$xASIND
Given the sine of an angle, the Arc Sine in Degrees routine returns
that angle (in degrees).
Format:
MTH$ASIND sine
MTH$DASIND sine
MTH$GASIND sine
Each of the above formats accepts as input one of
the floating-point types.
Arguments:
sine
VMS usage: floating_point
type: F_floating, D_floating, G_floating
access: read only
mechanism: by reference
Sine of the angle whose value (in degrees) is to be returned. The
sine argument is the address of a floating-point number that is this
sine. The absolute value of sine must be less than or equal to 1.
For MTH$ASIND, sine specifies an F_floating number. For MTH$DASIND,
sine specifies a D_floating number. For MTH$GASIND, sine specifies
a G_floating number.
MTH$xATAN
Given the tangent of an angle, the Arc Tangent in Radians routine
returns that angle (in radians).
Format:
MTH$ATAN tangent
MTH$DATAN tangent
MTH$GATAN tangent
Each of the above formats accepts as input one of
the floating-point types.
Arguments:
tangent
VMS usage: floating_point
type: F_floating, D_floating, G_floating
access: read only
mechanism: by reference
The tangent of the angle whose value (in radians) is to be returned.
The tangent argument is the address of a floating-point number that
is this tangent. For MTH$ATAN, tangent specifies an F_floating
number. For MTH$DATAN, tangent specifies a D_floating number. For
MTH$GATAN, tangent specifies a G_floating number.
MTH$xATAND
Given the tangent of an angle, the Arc Tangent in Degrees routine
returns that angle (in degrees).
Format:
MTH$ATAND tangent
MTH$DATAND tangent
MTH$GATAND tangent
Each of the above formats accepts as input one of
the floating-point types.
Arguments:
tangent
VMS usage: floating_point
type: F_floating, D_floating, G_floating
access: read only
mechanism: by reference
The tangent of the angle whose value (in degrees) is to be returned.
The tangent argument is the address of a floating-point number that
is this tangent. For MTH$ATAND, tangent specifies an F_floating
number. For MTH$DATAND, tangent specifies a D_floating number. For
MTH$GATAND, tangent specifies a G_floating number.
MTH$xATAN2
Given sine and cosine, the Arc Tangent in Radians with Two Arguments
routine returns the angle (in radians) whose tangent is given by the
quotient of sine and cosine, (sine/cosine).
Format:
MTH$ATAN2 sine ,cosine
MTH$DATAN2 sine ,cosine
MTH$GATAN2 sine ,cosine
Each of the above formats accepts as input one of
the floating-point types.
Arguments:
sine
VMS usage: floating_point
type: F_floating, D_floating, G_floating
access: read only
mechanism: by reference
Dividend. The sine argument is the address of a floating-point
number that is this dividend. For MTH$ATAN2, sine specifies an
F_floating number. For MTH$DATAN2, sine specifies a D_floating
number. For MTH$GATAN2, sine specifies a G_floating number.
cosine
VMS usage: floating_point
type: F_floating, D_floating, G_floating
access: read only
mechanism: by reference
Divisor. The cosine argument is the address of a floating-point
number that is this divisor. For MTH$ATAN2, cosine specifies an
F_floating number. For MTH$DATAN2, cosine specifies a D_floating
number. For MTH$GATAN2, cosine specifies a G_floating number.
MTH$xATAND2
Given sine and cosine, the Arc Tangent in Degrees with Two Arguments
routine returns the angle (in degrees) whose tangent is given by the
quotient of sine and cosine, (sine/cosine).
Format:
MTH$ATAND2 sine ,cosine
MTH$DATAND2 sine ,cosine
MTH$GATAND2 sine ,cosine
Each of the above formats accepts as input one of
the floating-point types.
Arguments:
sine
VMS usage: floating_point
type: F_floating, D_floating, G_floating
access: read only
mechanism: by reference
Dividend. The sine argument is the address of a floating-point
number that is this dividend. For MTH$ATAND2, sine specifies an
F_floating number. For MTH$DATAND2, sine specifies a D_floating
number. For MTH$GATAND2, sine specifies a G_floating number.
cosine
VMS usage: floating_point
type: F_floating, D_floating, G_floating
access: read only
mechanism: by reference
Divisor. The cosine argument is the address of a floating-point
number that is this divisor. For MTH$ATAND2, cosine specifies an
F_floating number. For MTH$DATAND2, cosine specifies a D_floating
number. For MTH$GATAND2, cosine specifies a G_floating number.
MTH$xATANH
Given the hyperbolic tangent of an angle, the Hyperbolic Arc Tangent
routine returns the hyperbolic arc tangent of that angle.
Format:
MTH$ATANH hyperbolic-tangent
MTH$DATANH hyperbolic-tangent
MTH$GATANH hyperbolic-tangent
Each of the above formats accepts as input one of
the floating-point types.
Arguments:
hyperbolic-tangent
VMS usage: floating_point
type: F_floating, D_floating, G_floating
access: read only
mechanism: by reference
Hyperbolic tangent of an angle. The hyperbolic-tangent argument is
the address of a floating-point number that is this hyperbolic
tangent. For MTH$ATANH, hyperbolic-tangent specifies an F_floating
number. For MTH$DATANH, hyperbolic-tangent specifies a D_floating
number. For MTH$GATANH, hyperbolic-tangent specifies a G_floating
number.
MTH$CxABS
The Complex Absolute Value routine returns the absolute value of a
complex number (r,i).
Format:
MTH$CABS complex-number
MTH$CDABS complex-number
MTH$CGABS complex-number
Each of the above three formats accepts as input one
of the three floating-point complex types.
ARGUMENT
complex-number
VMS usage: complex_number
type: F_floating complex, D_floating complex, G_floating complex
access: read only
mechanism: by reference
A complex number (r,i), where r and i are both floating-point
complex values. The complex-number argument is the address of this
complex number. For MTH$CABS, complex-number specifies an
F_floating complex number. For MTH$CDABS, complex-number specifies
a D_floating complex number. For MTH$CGABS, complex-number
specifies a G_floating complex number.
MTH$CCOS
The Complex Cosine (F-floating Value) routine returns the complex
cosine of a complex number as an F-floating value.
Format:
MTH$CCOS complex-number
Arguments:
complex-number
VMS usage: complex_number
type: F_floating complex
access: read only
mechanism: by reference
A complex number (r,i) where r and i are floating-point numbers.
The complex-number argument is the address of this complex number.
For MTH$CCOS, complex-number specifies an F_floating complex number.
MTH$CxCOS
The Complex Cosine routine returns the complex cosine of a complex
number.
Format:
MTH$CDCOS complex-cosine ,complex-number
MTH$CGCOS complex-cosine ,complex-number
Each of the above formats accepts as input one of
the floating-point complex types.
Arguments:
complex-cosine
VMS usage: complex_number
type: D_floating complex, G_floating complex
access: write only
mechanism: by reference
Complex cosine of the complex-number. The complex cosine routines
that have D_floating and G_floating complex input values write the
address of the complex cosine into the complex-cosine argument. For
MTH$CDCOS, the complex-cosine argument specifies a D_floating
complex number. For MTH$CGCOS, the complex-number argument
specifies a G_floating complex number.
complex-number
VMS usage: complex_number
type: D_floating complex, G_floating complex
access: read only
mechanism: by reference
A complex number (r,i) where r and i are floating-point numbers.
The complex-number argument is the address of this complex number.
For MTH$CDCOS, complex-number specifies a D_floating complex number.
For MTH$CGCOS, complex-number specifies a G_floating complex number.
MTH$CEXP
The Complex Exponential (F-floating Value) routine returns the
complex exponential of a complex number as an F-floating value.
Format:
MTH$CEXP complex-number
Arguments:
complex-number
VMS usage: complex_number
type: F_floating complex
access: read only
mechanism: by reference
Complex number whose complex exponential is to be returned. This
complex number has the form (r,i), where "r" is the real part and
"i" is the imaginary part. The complex-number argument is the
address of this complex number. For MTH$CEXP, complex-number
specifies an F_floating number.
MTH$CxEXP
The Complex Exponential routine returns the complex exponential of a
complex number.
Format:
MTH$CDEXP complex-exponent ,complex-number
MTH$CGEXP complex-exponent ,complex-number
Each of the above formats accepts as input one of
the floating-point complex types.
Arguments:
complex-exponent
VMS usage: complex_number
type: D_floating complex, G_floating complex
access: write only
mechanism: by reference
Complex exponential of complex-number. The complex exponential
routines that have D_floating complex and G_floating complex input
values write the complex-exponent into this argument. For
MTH$CDEXP, complex-exponent argument specifies a D_floating complex
number. For MTH$CGEXP, complex-exponent specifies a G_floating
complex number.
complex-number
VMS usage: complex_number
type: D_floating complex, G_floating complex
access: read only
mechanism: by reference
Complex number whose complex exponential is to be returned. This
complex number has the form (r,i), where "r" is the real part and
"i" is the imaginary part. The complex-number argument is the
address of this complex number. For MTH$CDEXP, complex-number
specifies a D_floating number. For MTH$CGEXP, complex-number
specifies a G_floating number.
MTH$CLOG
The Complex Natural Logarithm (F-floating Value) routine returns the
complex natural logarithm of a complex number as an F-floating
value.
Format:
MTH$CLOG complex-number
Arguments:
complex-number
VMS usage: complex_number
type: F_floating complex
access: read only
mechanism: by reference
Complex number whose complex natural logarithm is to be returned.
This complex number has the form (r,i), where "r" is the real part
and "i" is the imaginary part. The complex-number argument is the
address of this complex number. For MTH$CLOG, complex-number
specifies an F_floating number.
MTH$CxLOG
The Complex Natural Logarithm routine returns the complex natural
logarithm of a complex number.
Format:
MTH$CDLOG complex-natural-log ,complex-number
MTH$CGLOG complex-natural-log ,complex-number
Each of the above formats accepts as input one of
the floating-point complex types.
Arguments:
complex-natural-log
VMS usage: complex_number
type: D_floating complex, G_floating complex
access: write only
mechanism: by reference
Natural logarithm of the complex number specified by complex-number.
The complex natural logarithm routines that have D_floating complex
and G_floating complex input values write the address of the complex
natural logarithm into complex-natural-log. For MTH$CDLOG, the
complex-natural-log argument specifies a D_floating complex number.
For MTH$CGLOG, the complex-natural-log argument specifies a
G_floating complex number.
complex-number
VMS usage: complex_number
type: D_floating complex, G_floating complex
access: read only
mechanism: by reference
Complex number whose complex natural logarithm is to be returned.
This complex number has the form (r,i), where "r" is the real part
and "i" is the imaginary part. The complex-number argument is the
address of this complex number. For MTH$CDLOG, complex-number
specifies a D_floating number. For MTH$CGLOG, complex-number
specifies a G_floating number.
MTH$CMPLX
The Complex Number Made from F-floating-Point routine returns a
complex number from two floating-point input values.
Format:
MTH$CMPLX real-part ,imaginary-part
Arguments:
real-part
VMS usage: floating_point
type: F_floating
access: read only
mechanism: by reference
Real part of a complex number. The real-part argument is the
address of a floating-point number that contains this real part, r
of (r,i). For MTH$CMPLX, real-part specifies an F_floating number.
imaginary-part
VMS usage: floating_point
type: F_floating
access: read only
mechanism: by reference
Imaginary part of a complex number. The imag-parg argument is the
address of a floating-point number that contains this imaginary
part, i of (r,i). For MTH$CMPLX, imaginary-part specifies an
F_floating number.
MTH$xCMPLX
The Complex Number Made from D- or G-floating-Point routine returns
a complex number from two D- or G-floating input values.
Format:
MTH$DCMPLX complx ,real-part ,imaginary-part
MTH$GCMPLX complx ,real-part ,imaginary-part
Each of the above formats accepts as input one of
floating-point complex types.
Arguments:
complx
VMS usage: complex_number
type: D_floating complex, G_floating complex
access: write only
mechanism: by reference
The floating-point complex value of a complex number. The complex
exponential functions that have D_floating complex and G_floating
complex input values write the address of this floating-point
complex value into complx. For MTH$DCMPLX, complx specifies a
D_floating complex number. For MTH$GCMPLX, complx specifies a
G_floating complex number. For MTH$CMPLX, complx is not used.
real-part
VMS usage: floating_point
type: D_floating, G_floating
access: read only
mechanism: by reference
Real part of a complex number. The real-part argument is the
address of a floating-point number that contains this real part, r
of (r,i). For MTH$DCMPLX, real-part specifies a D_floating number.
For MTH$GCMPLX, real-part specifies a G_floating number.
imaginary-part
VMS usage: floating_point
type: D_floating, G_floating
access: read only
mechanism: by reference
Imaginary part of a complex number. The imag-parg argument is the
address of a floating-point number that contains this imaginary
part, i of (r,i). For MTH$DCMPLX, imaginary-part specifies a
D_floating number. For MTH$GCMPLX, imaginary-part specifies a
G_floating number.
MTH$CONJG
The Conjugate of a Complex Number (F-floating Value) routine returns
the complex conjugate (r,-i) of a complex number (r,i) as an
F-floating value.
Format:
MTH$CONJG complex-number
Arguments:
complex-number
VMS usage: complex_number
type: F_floating complex
access: read only
mechanism: by reference
A complex number (r,i), where r and i are floating-point numbers.
The complex-number argument is the address of this floating-point
complex number. For MTH$CONJG, complex-number specifies an
F_floating number.
MTH$xCONJG
The Conjugate of a Complex Number routine returns the complex
conjugate (r,-i) of a complex number (r,i).
Format:
MTH$DCONJG complex-conjugate ,complex-number
MTH$GCONJG complex-conjugate ,complex-number
Each of the above formats accepts as input one of
the floating-point complex types.
Arguments:
complex-conjugate
VMS usage: complex_number
type: D_floating complex, G_floating complex
access: write only
mechanism: by reference
The complex conjugate (r,-i) of the complex number specified by
complex-number. MTH$DCONJG and MTH$GCONJG write the address of this
complex conjugate into complex-conjugate. For MTH$DCONJG, the
complex-conjugate argument specifies the address of a D_floating
complex number. For MTH$GCONJG, the complex-conjugate argument
specifies the address of a G_floating complex number.
complex-number
VMS usage: complex_number
type: D_floating complex, G_floating complex
access: read only
mechanism: by reference
A complex number (r,i), where r and i are floating-point numbers.
The complex-number argument is the address of this floating-point
complex number. For MTH$DCONJG, complex-number specifies a
D_floating number. For MTH$GCONJG, complex-number specifies a
G_floating number.
MTH$xCOS
The Cosine of Angle Expressed in Radians routine returns the cosine
of a given angle (in radians).
Format:
MTH$COS angle-in-radians
MTH$DCOS angle-in-radians
MTH$GCOS angle-in-radians
Each of the above formats accepts as input one of
the floating-point types.
Arguments:
angle-in-radians
VMS usage: floating_point
type: F_floating, D_floating, G_floating
access: read only
mechanism: by reference
The angle in radians. The angle-in-radians argument is the address
of a floating-point number. For MTH$COS, angle-in-radians is an
F_floating number. For MTH$DCOS, angle-in-radians specifies a
D_floating number. For MTH$GCOS, angle-in-radians specifies a
G_floating number.
MTH$xCOSD
The Cosine of Angle Expressed in Degrees routine returns the cosine
of a given angle (in degrees).
Format:
MTH$COSD angle-in-degrees
MTH$DCOSD angle-in-degrees
MTH$GCOSD angle-in-degrees
Each of the above formats accepts as input one of
the floating-point types.
Arguments:
angle-in-degrees
VMS usage: floating_point
type: F_floating, D_floating, G_floating
access: read only
mechanism: by reference
Angle (in degrees). The angle-in-degrees argument is the address of
a floating-point number. For MTH$COSD, angle-in-degrees specifies
an F_floating number. For MTH$DCOSD, angle-in-degrees specifies a
D_floating number. For MTH$GCOSD, angle-in-degrees specifies a
G_floating number.
MTH$xCOSH
The Hyperbolic Cosine routine returns the hyperbolic cosine of the
input value.
Format:
MTH$COSH floating-point-input-value
MTH$DCOSH floating-point-input-value
MTH$GCOSH floating-point-input-value
Each of the above formats accepts as input one of
the floating-point types.
Arguments:
floating-point-input-value
VMS usage: floating_point
type: F_floating, D_floating, G_floating
access: read only
mechanism: by reference
The input value. The floating-point-input-value argument is the
address of this input value. For MTH$COSH,
floating-point-input-value specifies an F_floating number. For
MTH$DCOSH, floating-point-input-value specifies a D_floating number.
For MTH$GCOSH, floating-point-input-value specifies a G_floating
number.
MTH$CSIN
The Complex Sine of Complex Number (F-floating Value) routine
returns the complex sine of a complex number (r,i) as an F-floating
value.
Format:
MTH$CSIN complex-number
Arguments:
complex-number
VMS usage: complex_number
type: F_floating complex
access: read only
mechanism: by reference
A complex number (r,i), where r and i are floating-point numbers.
The complex-number argument is the address of this complex number.
For MTH$CSIN, complex-number specifies an F_floating complex number.
MTH$CxSIN
The Complex Sine of Complex Number routine returns the complex sine
of a complex number (r,i).
Format:
MTH$CDSIN complex-sine ,complex-number
MTH$CGSIN complex-sine ,complex-number
Each of the above formats accepts as input one of
the floating-point complex types.
Arguments:
complex-sine
VMS usage: complex_number
type: D_floating complex, G_floating complex
access: write only
mechanism: by reference
Complex sine of the complex number. The complex sine routines with
D_floating complex and G_floating complex input values write the
complex sine into this complex-sine argument. For MTH$CDSIN,
complex-sine specifies a D_floating complex number. For MTH$CGSIN,
complex-sine specifies a G_floating complex number.
complex-number
VMS usage: complex_number
type: D_floating complex, G_floating complex
access: read only
mechanism: by reference
A complex number (r,i), where r and i are floating-point numbers.
The complex-number argument is the address of this complex number.
For MTH$CDSIN, complex-number specifies a D_floating complex number.
For MTH$CGSIN, complex-number specifies a G_floating complex number.
MTH$CSQRT
The Complex Square Root (F-floating Value) routine returns the
complex square root of a complex number (r,i).
Format:
MTH$CSQRT complex-number
Arguments:
complex-number
VMS usage: complex_number
type: F_floating complex
access: read only
mechanism: by reference
Complex number (r,i). The complex-number argument contains the
address of this complex number. For MTH$CSQRT, complex-number
specifies an F_floating number.
MTH$CxSQRT
The Complex Square Root routine returns the complex square root of a
complex number (r,i).
Format:
MTH$CDSQRT complex-square-root ,complex-number
MTH$CGSQRT complex-square-root ,complex-number
Each of the above formats accepts as input one of
the floating-point complex types.
Arguments:
complex-square-root
VMS usage: complex_number
type: D_floating complex, G_floating complex
access: write only
mechanism: by reference
Complex square root of the complex number specified by
complex-number. The complex square root routines that have
D_floating complex and G_floating complex input values write the
complex square root into complex-square-root. For MTH$CDSQRT,
complex-square-root specifies a D_floating complex number. For
MTH$CGSQRT, complex-square-root specifies a G_floating complex
number.
complex-number
VMS usage: complex_number
type: D_floating complex, G_floating complex
access: read only
mechanism: by reference
Complex number (r,i). The complex-number argument contains the
address of this complex number. For MTH$CDSQRT, complex-number
specifies a D_floating number. For MTH$CGSQRT, complex-number
specifies a G_floating number.
MTH$CVT x x
The Convert One Double-Precision Value routines convert one
double-precision value to the destination data type and return the
result as a function value. MTH$CVT_D_G converts a D_floating value
to G_floating and MTH$CVT_G_D converts a G_floating value to a
D_floating value.
Format:
MTH$CVT_D_G floating-point-input-val
MTH$CVT_G_D floating-point-input-val
ARGUMENT
floating-point-input-val
VMS usage: floating_point
type: D_floating, G_floating
access: read only
mechanism: by reference
The input value to be converted. The floating-point-input-val
argument is the address of this input value. For MTH$CVT_D_G, the
floating-point-input-val argument specifies a D_floating number.
For MTH$CVT_G_D, the floating-point-input-val argument specifies
a G_floating number.
MTH$CVT xA xA
The Convert an Array of Double-Precision Values routines convert a
contiguous array of double-precision values to the destination data
type and return the results as an array. MTH$CVT_DA_GA converts
D_floating values to G_floating and MTH$CVT_GA_DA converts
G_floating values to D_floating.
Format:
MTH$CVT_DA_GA floating-point-input-array
,floating-point-dest-array [,array-size]
MTH$CVT_GA_DA floating-point-input-array
,floating-point-dest-array [,array-size]
Arguments:
floating-point-input-array
VMS usage: floating_point
type: D_floating, G_floating
access: read only
mechanism: by reference, array reference
Input array of values to be converted. The
floating-point-input-array argument is the address of an array of
floating-point numbers. For MTH$CVT_DA_GA,
floating-point-input-array specifies an array of D_floating numbers.
For MTH$CVT_GA_DA, floating-point-input-array specifies an array of
a G_floating numbers.
floating-point-dest-array
VMS usage: floating_point
type: D_floating, G_floating
access: write only
mechanism: by reference, array reference
Output array of converted values. The floating-point-dest-array
argument is the address of an array of floating-point numbers. For
MTH$CVT_DA_GA, floating-point-dest-array specifies an array of
G_floating numbers. For MTH$CVT_GA_DA, floating-point-dest-array
specifies an array of D_floating numbers.
array-size
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Number of array elements to be converted. The default value is 1.
The array-size argument is the address of this number of elements.
MTH$xEXP
The Exponential routine returns the exponential of the input value.
Format:
MTH$EXP floating-point-input-value
MTH$DEXP floating-point-input-value
MTH$GEXP floating-point-input-value
Each of the above formats accepts as input one of
the floating-point types.
Arguments:
floating-point-input-value
VMS usage: floating_point
type: F_floating, D_floating, G_floating
access: read only
mechanism: by reference
The input value. The floating-point-input-value argument is the
address of a floating-point number. For MTH$EXP,
floating-point-input-value specifies an F_floating number. For
MTH$DEXP, floating-point-input-value specifies a D_floating number.
For MTH$GEXP, floating-point-input-value specifies a G_floating
number.
MTH$HACOS
Given the cosine of an angle, the Arc Cosine of Angle Expressed in
Radians (H-floating Value) routine returns that angle (in radians)
in H-floating-point precision.
Format:
MTH$HACOS h-radians ,cosine
Arguments:
h-radians
VMS usage: floating_point
type: H_floating
access: write only
mechanism: by reference
Angle (in radians) whose cosine is specified by cosine. The
h-radians argument is the address of an H_floating number that is
this angle. MTH$HACOS writes the address of the angle into
h-radians. The h-radians argument is used only by the MTH$HACOS
routine.
cosine
VMS usage: floating_point
type: H_floating
access: read only
mechanism: by reference
The cosine of the angle whose value (in radians) is to be returned.
The cosine argument is the address of a floating-point number that
is this cosine. The absolute value of cosine must be less than or
equal to 1. For MTH$HACOS, cosine specifies an H_floating number.
MTH$HACOSD
Given the cosine of an angle, the Arc Cosine of Angle Expressed in
Degrees (H-Floating Value) routine returns that angle (in degrees)
as an H-floating value.
Format:
MTH$HACOSD h-degrees ,cosine
Arguments:
h-degrees
VMS usage: floating_point
type: H_floating
access: write only
mechanism: by reference
Angle (in degrees) whose cosine is specified by cosine. The
h-degrees argument is the address of an H_floating number that is
this angle. MTH$HACOSD writes the address of the angle into
h-degrees. The h-degrees argument is used only by the MTH$HACOSD
routine.
cosine
VMS usage: floating_point
type: H_floating
access: read only
mechanism: by reference
Cosine of the angle whose value (in degrees) is to be returned. The
cosine argument is the address of a floating-point number that is
this cosine. The absolute value of cosine must be less than or
equal to 1. For MTH$HACOSD, cosine specifies an H_floating number.
MTH$HASIN
Given the sine of an angle, the Arc Sine in Radians (H-floating
Value) routine returns that angle (in radians) as an H-floating
value.
Format:
MTH$HASIN h-radians ,sine
Arguments:
h-radians
VMS usage: floating_point
type: H_floating
access: write only
mechanism: by reference
Angle (in radians) whose sine is specified by sine. The h-radians
argument is the address of an H_floating number that is this angle.
MTH$HASIN writes the address of the angle into h-radians. The
h-radians argument is used only by the MTH$HASIN routine.
sine
VMS usage: floating_point
type: H_floating
access: read only
mechanism: by reference
The sine of the angle whose value (in radians) is to be returned.
The sine argument is the address of a floating-point number that is
this sine. The absolute value of sine must be less than or equal to
1. For MTH$HASIN, sine specifies an H_floating number.
MTH$HASIND
Given the sine of an angle, the Arc Sine in Degrees (H-Floating
Value) routine returns that angle (in degrees) as an H-floating
value.
Format:
MTH$HASIND h-degrees ,sine
Arguments:
h-degrees
VMS usage: floating_point
type: H_floating
access: write only
mechanism: by reference
Angle (in degrees) whose sine is specified by sine. The h-degrees
argument is the address of an H_floating number that is this angle.
MTH$HASIND writes the address of the angle into h-degrees. The
h-degrees argument is used only by the MTH$HASIND routine.
sine
VMS usage: floating_point
type: H_floating
access: read only
mechanism: by reference
Sine of the angle whose value (in degrees) is to be returned. The
sine argument is the address of a floating-point number that is this
sine. The absolute value of sine must be less than or equal to 1.
For MTH$HASIND, sine specifies an H_floating number.
MTH$HATAN
Given the tangent of an angle, the Arc Tangent in Radians
(H-floating Value) routine returns that angle (in radians) as an
H-floating value.
Format:
MTH$HATAN h-radians ,tangent
Arguments:
h-radians
VMS usage: floating_point
type: H_floating
access: write only
mechanism: by reference
Angle (in radians) whose tangent is specified by tangent. The
h-radians argument is the address of an H_floating number that is
this angle. MTH$HATAN writes the address of the angle into
h-radians. The h-radians argument is used only by the MTH$HATAN
routine.
tangent
VMS usage: floating_point
type: H_floating
access: read only
mechanism: by reference
The tangent of the angle whose value (in radians) is to be returned.
The tangent argument is the address of a floating-point number that
is this tangent. For MTH$HATAN, tangent specifies an H_floating
number.
MTH$HATAND
Given the tangent of an angle, the Arc Tangent in Degrees
(H-floating Value) routine returns that angle (in degrees) as an
H-floating point value.
Format:
MTH$HATAND h-degrees ,tangent
Arguments:
h-degrees
VMS usage: floating_point
type: H_floating
access: write only
mechanism: by reference
Angle (in degrees) whose tangent is specified by tangent. The
h-degrees argument is the address of an H_floating number that is
this angle. MTH$HATAND writes the address of the angle into
h-degrees. The h-degrees argument is used only by the MTH$HATAND
routine.
tangent
VMS usage: floating_point
type: H_floating
access: read only
mechanism: by reference
The tangent of the angle whose value (in degrees) is to be returned.
The tangent argument is the address of a floating-point number that
is this tangent. For MTH$HATAND, tangent specifies an H_floating
number.
MTH$HATAN2
Given sine and cosine, the Arc Tangent in Radians (H-floating Value)
with Two Arguments routine returns the angle (in radians) as an
H-floating value whose tangent is given by the quotient of sine and
cosine, (sine/cosine).
Format:
MTH$HATAN2 h-radians ,sine ,cosine
Arguments:
h-radians
VMS usage: floating_point
type: H_floating
access: write only
mechanism: by reference
Angle (in radians) whose tangent is specified by (sine/cosine). The
h-radians argument is the address of an H_floating number that is
this angle. MTH$HATAN2 writes the address of the angle into
h-radians. The h-radians argument is used only by the MTH$HATAN2
routine.
sine
VMS usage: floating_point
type: H_floating
access: read only
mechanism: by reference
Dividend. The sine argument is the address of a floating-point
number that is this dividend. For MTH$HATAN2, sine specifies an
H_floating number.
cosine
VMS usage: floating_point
type: H_floating
access: read only
mechanism: by reference
Divisor. The cosine argument is the address of a floating-point
number that is this divisor. For MTH$HATAN2, cosine specifies an
H_floating number.
MTH$HATAND2
Given sine and cosine, MTH$xHTAND2 returns the angle (in degrees)
whose tangent is given by the quotient of sine and cosine,
(sine/cosine).
Format:
MTH$HATAND2 h-degrees ,sine ,cosine
Arguments:
h-degrees
VMS usage: floating_point
type: H_floating
access: write only
mechanism: by reference
Angle (in degrees) whose tangent is specified by (sine/cosine). The
h-degrees argument is the address of an H_floating number that is
this angle. MTH$HATAND2 writes the address of the angle into
h-degrees. The h-degrees argument is used only by the MTH$HATAND2
routine.
sine
VMS usage: floating_point
type: H_floating
access: read only
mechanism: by reference
Dividend. The sine argument is the address of a floating-point
number that is this dividend. For MTH$HATAND2, sine specifies an
H_floating number.
cosine
VMS usage: floating_point
type: H_floating
access: read only
mechanism: by reference
Divisor. The cosine argument is the address of a floating-point
number that is this divisor. For MTH$HATAND2, cosine specifies an
H_floating number.
MTH$HATANH
Given the hyperbolic tangent of an angle, the Hyperbolic Arc Tangent
(H-floating Value) routine returns the hyperbolic arc tangent (as an
H-floating value) of that angle.
Format:
MTH$HATANH h-atanh ,hyperbolic-tangent
Arguments:
h-atanh
VMS usage: floating_point
type: H_floating
access: write only
mechanism: by reference
Hyperbolic arc tangent of the hyperbolic tangent specified by
hyperbolic-tangent. The h-atanh argument is the address of an
H_floating number that is this hyperbolic arc tangent. MTH$HATANH
writes the address of the hyperbolic arc tangent into h-atanh. The
h-atanh argument is used only by the MTH$HATANH routine.
hyperbolic-tangent
VMS usage: floating_point
type: H_floating
access: read only
mechanism: by reference
Hyperbolic tangent of an angle. The hyperbolic-tangent argument is
the address of a floating-point number that is this hyperbolic
tangent. For MTH$HATANH, hyperbolic-tangent specifies an H_floating
number.
MTH$HCOS
The Cosine of Angle Expressed in Radians (H-floating Value) routine
returns the cosine of a given angle (in radians) as an H-floating
value.
Format:
MTH$HCOS h-cosine ,angle-in-radians
Arguments:
h-cosine
VMS usage: floating_point
type: H_floating
access: write only
mechanism: by reference
Cosine of the angle specified by angle-in-radians. The h-cosine
argument is the address of an H_floating number that is this cosine.
MTH$HCOS writes the address of the cosine into h-cosine. The
h-cosine argument is used only by the MTH$HCOS routine.
angle-in-radians
VMS usage: floating_point
type: H_floating
access: read only
mechanism: by reference
The angle in radians. The angle-in-radians argument is the address
of a floating-point number. For MTH$HCOS, angle-in-radians
specifies an H_floating number.
MTH$HCOSD
The Cosine of Angle Expressed in Degrees (H-floating Value) routine
returns the cosine of a given angle (in degrees) as an H-floating
value.
Format:
MTH$HCOSD h-cosine ,angle-in-degrees
Arguments:
h-cosine
VMS usage: floating_point
type: H_floating
access: write only
mechanism: by reference
Cosine of the angle specified by angle-in-degrees. The h-cosine
argument is the address of an H_floating number that is this cosine.
MTH$HCOSD writes this cosine into h-cosine. The h-cosine argument
is used only by the MTH$HCOSD routine.
angle-in-degrees
VMS usage: floating_point
type: H_floating
access: read only
mechanism: by reference
Angle (in degrees). The angle-in-degrees argument is the address of
a floating-point number. For MTH$HCOSD, angle-in-degrees specifies
an H_floating number.
MTH$HCOSH
The Hyperbolic Cosine routine returns the hyperbolic cosine of the
input value as an H-floating value.
Format:
MTH$HCOSH h-cosh ,floating-point-input-value
Arguments:
h-cosh
VMS usage: floating_point
type: H_floating
access: write only
mechanism: by reference
Hyperbolic cosine of the input value specified by
floating-point-input-value. The h-cosh argument is the address of
an H_floating number that is this hyperbolic cosine. MTH$HCOSH
writes the address of the hyperbolic cosine into h-cosh. The h-cosh
argument is used only by the MTH$HCOSH routine.
floating-point-input-value
VMS usage: floating_point
type: H_floating
access: read only
mechanism: by reference
The input value. The floating-point-input-value argument is the
address of this input value. For MTH$HCOSH,
floating-point-input-value specifies an H_floating number.
MTH$HEXP
The Exponential routine returns the exponential of the input value
as an H-floating value.
Format:
MTH$HEXP h-exp ,floating-point-input-value
Arguments:
h-exp
VMS usage: floating_point
type: H_floating
access: write only
mechanism: by reference
Exponential of the input value specified by
floating-point-input-value. The h-exp argument is the address of an
H_floating number that is this exponential. MTH$HEXP writes the
address of the exponential into h-exp. The h-exp argument is used
only by the MTH$HEXP routine.
floating-point-input-value
VMS usage: floating_point
type: H_floating
access: read only
mechanism: by reference
The input value. The floating-point-input-value argument is the
address of a floating-point number. For MTH$HEXP,
floating-point-input-value specifies an H_floating number.
MTH$HLOG
The Logarithm ,Natural (H-floating Value) routine returns the
natural (base e) logarithm of the input argument as an H-floating
value.
Format:
MTH$HLOG h-natlog ,floating-point-input-value
Arguments:
h-natlog
VMS usage: floating_point
type: H_floating
access: write only
mechanism: by reference
Natural logarithm of floating-point-input-value. The h-natlog
argument is the address of an H_floating number that is this natural
logarithm. MTH$HLOG writes the address of this natural logarithm
into h-natlog. The h-natlog argument is used only by the MTH$HLOG
routine.
floating-point-input-value
VMS usage: floating_point
type: H_floating
access: read only
mechanism: by reference
The input value. The floating-point-input-value argument is the
address of a floating-point number that is this value. For
MTH$HLOG, floating-point-input-value specifies an H_floating number.
MTH$HLOG2
The Logarithm, Base 2 (H-floating Value) routine returns the base 2
logarithm of the input value specified by floating-point-input-value
as an H-floating value.
Format:
MTH$HLOG2 h-log2 ,floating-point-input-value
Arguments:
h-log2
VMS usage: floating_point
type: H_floating
access: write only
mechanism: by reference
Base 2 logarithm of floating-point-input-value. The h-log2 argument
is the address of an H_floating number that is this base 2
logarithm. MTH$HLOG2 writes the address of this logarithm into
h-log2. The h-log2 argument is used only by the MTH$HLOG2 routine.
floating-point-input-value
VMS usage: floating_point
type: H_floating
access: read only
mechanism: by reference
The input value. The floating-point-input-value argument is the
address of a floating-point number that is this input value. For
MTH$HLOG2, floating-point-input-value specifies an H_floating
number.
MTH$HLOG10
The Logarithm, Common (H-floating Value) routine returns the common
(base 10) logarithm of the input argument as an H-floating value.
Format:
MTH$HLOG10 h-log10 ,floating-point-input-value
Arguments:
h-log10
VMS usage: floating_point
type: H_floating
access: write only
mechanism: by reference
Common logarithm of the input value specified by
floating-point-input-value. The h-log10 argument is the address of
an H_floating number that is this common logarithm. MTH$HLOG10
writes the address of the common logarithm into h-log10. The
h-log10 argument is used only by the MTH$HLOG10 routine.
floating-point-input-value
VMS usage: floating_point
type: H_floating
access: read only
mechanism: by reference
The input value. The floating-point-input-value argument is the
address of a floating-point number. For MTH$HLOG10,
floating-point-input-value specifies an H_floating number.
MTH$HSIN
The Sine of Angle Expressed in Radians (H-floating Value) routine
returns the sine of a given angle (in radians) as an H-floating
value.
Format:
MTH$HSIN h-sine ,angle-in-radians
Arguments:
h-sine
VMS usage: floating_point
type: H_floating
access: write only
mechanism: by reference
The sine of the angle specified by angle-in-radians. The h-sine
argument is the address of an H_floating number that is this sine.
MTH$HSIN writes the address of the sine into h-sine. The h-sine
argument is used only by the MTH$HSIN routine.
angle-in-radians
VMS usage: floating_point
type: H_floating
access: read only
mechanism: by reference
Angle (in radians). The angle-in-radians argument is the address of
a floating-point number that is this angle. For MTH$HSIN,
angle-in-radians specifies an H_floating number.
MTH$HSIND
The Sine of Angle Expressed in Degrees (H-floating Value) routine
returns the sine of a given angle (in degrees) as an H-floating
value.
Format:
MTH$HSIND h-sine ,angle-in-degrees
Arguments:
h-sine
VMS usage: floating_point
type: H_floating
access: write only
mechanism: by reference
Sine of the angle specified by angle-in-degrees. The h-sine
argument is the address of an H_floating number that is this sine.
MTH$HSIND writes the address of the angle into h-sine. The h-sine
argument is used only by the MTH$HSIND routine.
angle-in-degrees
VMS usage: floating_point
type: H_floating
access: read only
mechanism: by reference
Angle (in degrees). The angle-in-degrees argument is the address of
a floating-point number that is this angle. For MTH$HSIND,
angle-in-degrees specifies an H_floating number.
MTH$HSINH
The Hyperbolic Sine (H-floating Value) routine returns the
hyperbolic sine of the input value specified by
floating-point-input-value as an H-floating value.
Format:
MTH$HSINH h-sinh ,floating-point-input-value
Arguments:
h-sinh
VMS usage: floating_point
type: H_floating
access: write only
mechanism: by reference
Hyperbolic sine of the input value specified by
floating-point-input-value. The h-sinh argument is the address of
an H_floating number that is this hyperbolic sine. MTH$HSINH writes
the address of the hyperbolic sine into h-sinh. The h-sinh argument
is used only by the MTH$HSINH routine.
floating-point-input-value
VMS usage: floating_point
type: H_floating
access: read only
mechanism: by reference
The input value. The floating-point-input-value argument is the
address of a floating-point number that is this value. For
MTH$HSINH, floating-point-input-value specifies an H_floating
number.
MTH$HSQRT
The Square Root (H-floating Value) routine returns the square root
of the input value floating-point-input-value as an H-floating
value.
Format:
MTH$HSQRT h-sqrt ,floating-point-input-value
Arguments:
h-sqrt
VMS usage: floating_point
type: H_floating
access: write only
mechanism: by reference
Square root of the input value specified by
floating-point-input-value. The h-sqrt argument is the address of
an H_floating number that is this square root. MTH$HSQRT writes the
address of the square root into h-sqrt. The h-sqrt argument is used
only by the MTH$HSQRT routine.
floating-point-input-value
VMS usage: floating_point
type: H_floating
access: read only
mechanism: by reference
Input value. The floating-point-input-value argument is the address
of a floating-point number that contains this input value. For
MTH$HSQRT, an H_floating number.
MTH$HTAN
The Tangent of Angle Expressed in Radians (H-floating Value) routine
returns the tangent of a given angle (in radians) as an H-floating
value.
Format:
MTH$HTAN h-tan ,angle-in-radians
Arguments:
h-tan
VMS usage: floating_point
type: H_floating
access: write only
mechanism: by reference
Tangent of the angle specified by angle-in-radians. The h-tan
argument is the address of an H_floating number that is this
tangent. MTH$HTAN writes the address of the tangent into h-tan.
The h-tan argument is used only by the MTH$HTAN routine.
angle-in-radians
VMS usage: floating_point
type: H_floating
access: read only
mechanism: by reference
The input angle (in radians). The angle-in-radians argument is the
address of a floating-point number that is this angle. For
MTH$HTAN, angle-in-radians specifies an H_floating number.
MTH$HTAND
The Tangent of Angle Expressed in Degrees (H-floating Value) routine
returns the tangent of a given angle (in degrees) as an H-floating
value.
Format:
MTH$HTAND h-tan ,angle-in-degrees
Arguments:
h-tan
VMS usage: floating_point
type: H_floating
access: write only
mechanism: by reference
Tangent of the angle specified by angle-in-degrees. The h-tan
argument is the address of an H_floating number that is this
tangent. MTH$HTAND writes the address of the tangent into h-tan.
The h-tan argument is used only by the MTH$HTAN routine.
angle-in-degrees
VMS usage: floating_point
type: H_floating
access: read only
mechanism: by reference
The input angle (in degrees). The angle-in-degrees argument is the
address of a floating-point number which is this angle. For
MTH$HTAND, angle-in-degrees specifies an H_floating number.
MTH$HTANH
The Compute the Hyperbolic Tangent (H-floating Value) routine
returns the hyperbolic tangent of the input value as an H-floating
value.
Format:
MTH$HTANH h-tanh ,floating-point-input-value
Arguments:
h-tanh
VMS usage: floating_point
type: H_floating
access: write only
mechanism: by reference
Hyperbolic tangent of the value specified by
floating-point-input-value. The h-tanh argument is the address of a
H_floating number that is this hyperbolic tangent. MTH$HTANH writes
the address of the hyperbolic tangent into h-tanh. The h-tanh
argument is used only by the MTH$TANH routine.
floating-point-input-value
VMS usage: floating_point
type: H_floating
access: read only
mechanism: by reference
The input value. The floating-point-input-value argument is the
address of a floating-point number that contains this input value.
For MTH$HTANH, floating-point-input-value specifies an H_floating
number.
MTH$xIMAG
The Imaginary Part of a Complex Number routine returns the imaginary
part of a complex number.
Format:
MTH$AIMAG complex-number
MTH$DIMAG complex-number
MTH$GIMAG complex-number
Each of the above three formats corresponds to one
of the three floating-point complex types.
ARGUMENT
complex-number
VMS usage: complex_number
type: F_floating complex, D_floating complex, G_floating complex
access: read only
mechanism: by reference
The input complex number. The complex-number argument is the
address of this floating-point complex number. For MTH$AIMAG,
complex-number specifies an F_floating number. For MTH$DIMAG,
complex-number specifies a D_floating number. For MTH$GIMAG,
complex-number specifies a G_floating number.
MTH$xLOG
The Logarithm, Natural routine returns the natural (base e)
logarithm of the input argument.
Format:
MTH$ALOG floating-point-input-value
MTH$DLOG floating-point-input-value
MTH$GLOG floating-point-input-value
Each of the above formats accepts as input one of
the floating-point types.
Arguments:
floating-point-input-value
VMS usage: floating_point
type: F_floating, D_floating, G_floating
access: read only
mechanism: by reference
The input value. The floating-point-input-value argument is the
address of a floating-point number that is this value. For
MTH$ALOG, floating-point-input-value specifies an F_floating number.
For MTH$DLOG, floating-point-input-value specifies a D_floating
number. For MTH$GLOG, floating-point-input-value specifies a
G_floating number.
MTH$xLOG2
The Logarithm, Base 2 routine returns the base 2 logarithm of the
input value specified by floating-point-input-value.
Format:
MTH$ALOG2 floating-point-input-value
MTH$DLOG2 floating-point-input-value
MTH$GLOG2 floating-point-input-value
Each of the above formats accepts as input one of
the floating-point types.
Arguments:
floating-point-input-value
VMS usage: floating_point
type: F_floating, D_floating, G_floating
access: read only
mechanism: by reference
The input value. The floating-point-input-value argument is the
address of a floating-point number that is this input value. For
MTH$ALOG2, floating-point-input-value specifies an F_floating
number. For MTH$DLOG2, floating-point-input-value specifies a
D_floating number. For MTH$GLOG2, floating-point-input-value
specifies a G_floating number.
MTH$xLOG10
The Logarithm, Common routine returns the common (base 10) logarithm
of the input argument.
Format:
MTH$ALOG10 floating-point-input-value
MTH$DLOG10 floating-point-input-value
MTH$GLOG10 floating-point-input-value
Each of the above formats accepts as input one of
the floating-point types.
Arguments:
floating-point-input-value
VMS usage: floating_point
type: F_floating, D_floating, G_floating
access: read only
mechanism: by reference
The input value. The floating-point-input-value argument is the
address of a floating-point number. For MTH$ALOG10,
floating-point-input-value specifies an F_floating number. For
MTH$DLOG10, floating-point-input-value specifies a D_floating
number. For MTH$GLOG10, floating-point-input-value specifies a
G_floating number.
MTH$RANDOM
The Random-Number Generator, Uniformly Distributed routine is a
general random-number generator.
Format:
MTH$RANDOM seed
ARGUMENT
seed
VMS usage: longword_unsigned
type: longword (unsigned)
access: modify
mechanism: by reference
The integer seed, a 32-bit number whose high-order 24 bits are
converted by MTH$RANDOM to an F_floating random number. The seed
argument is the address of an unsigned longword that contains this
integer seed. The seed is modified by each call to MTH$RANDOM.
MTH$xREAL
The Real Part of a Complex Number routine returns the real part of a
complex number.
Format:
MTH$REAL complex-number
MTH$DREAL complex-number
MTH$GREAL complex-number
Each of the above three formats accepts as input
one of the three floating-point complex types.
ARGUMENT
complex-number
VMS usage: complex_number
type: F_floating complex, D_floating complex, G_floating complex
access: read only
mechanism: by reference
The complex number whose real part is returned by MTH$REAL. The
complex-number argument is the address of this floating-point
complex number. For MTH$REAL, complex-number is an F_floating
complex number. For MTH$DREAL, complex-number is a D_floating
complex number. For MTH$GREAL, complex-number is a G_floating
complex number.
MTH$xSIN
The Sine of Angle Expressed in Radians routine returns the sine of a
given angle (in radians).
Format:
MTH$SIN angle-in-radians
MTH$DSIN angle-in-radians
MTH$GSIN angle-in-radians
Each of the above formats accepts as input one of
the floating-point types.
Arguments:
angle-in-radians
VMS usage: floating_point
type: F_floating, D_floating, G_floating
access: read only
mechanism: by reference
Angle (in radians). The angle-in-radians argument is the address of
a floating-point number that is this angle. For MTH$SIN,
angle-in-radians specifies an F_floating number. For MTH$DSIN,
angle-in-radians specifies a D_floating number. For MTH$GSIN,
angle-in-radians specifies a G_floating number.
MTH$xSINCOS
The Sine and Cosine of Angle Expressed in Radians routine returns
the sine and the cosine of a given angle (in radians).
Format:
MTH$SINCOS angle-in-radians ,sine ,cosine
MTH$DSINCOS angle-in-radians ,sine ,cosine
MTH$GSINCOS angle-in-radians ,sine ,cosine
MTH$HSINCOS angle-in-radians ,sine ,cosine
Each of the above four formats accepts as input one
of the four floating-point types.
Arguments:
angle-in-radians
VMS usage: floating_point
type: F_floating, D_floating, G_floating, H_floating
access: read only
mechanism: by reference
Angle (in radians) whose sine and cosine are to be returned. The
angle-in-radians argument is the address of a floating-point number
that is this angle. For MTH$SINCOS, angle-in-radians is an
F_floating number. For MTH$DSINCOS, angle-in-radians is a
D_floating number. For MTH$GSINCOS, angle-in-radians is a
G_floating number. For MTH$HSINCOS, angle-in-radians is an
H_floating number.
sine
VMS usage: floating_point
type: F_floating, D_floating, G_floating, H_floating
access: write only
mechanism: by reference
Sine of the angle specified by angle-in-radians. The sine argument
is the address of a floating-point number. MTH$SINCOS writes an
F_floating number into sine. MTH$DSINCOS writes a D_floating number
into sine. MTH$GSINCOS writes a G_floating number into sine.
MTH$HSINCOS writes an H_floating number into sine.
cosine
VMS usage: floating_point
type: F_floating, D_floating, G_floating, H_floating
access: write only
mechanism: by reference
Cosine of the angle specified by angle-in-radians. The cosine
argument is the address of a floating-point number. MTH$SINCOS
writes an F_floating number into cosine. MTH$DSINCOS writes a
D_floating number into cosine. MTH$GSINCOS writes a G_floating
number into cosine. MTH$HSINCOS writes an H_floating number into
cosine.
MTH$xSINCOSD
The Sine and Cosine of Angle Expressed in Degrees routine returns
the sine and cosine of a given angle (in degrees).
Format:
MTH$SINCOSD angle-in-degrees ,sine ,cosine
MTH$DSINCOSD angle-in-degrees ,sine ,cosine
MTH$GSINCOSD angle-in-degrees ,sine ,cosine
MTH$HSINCOSD angle-in-degrees ,sine ,cosine
Each of the above four formats accepts as input one
of the four floating-point types.
Arguments:
angle-in-degrees
VMS usage: floating_point
type: F_floating, D_floating, G_floating, H_floating
access: read only
mechanism: by reference
Angle (in degrees) whose sine and cosine are returned by
MTH$xSINCOSD. The angle-in-degrees argument is the address of a
floating-point number that is this angle. For MTH$SINCOSD,
angle-in-degrees is an F_floating number. For MTH$DSINCOSD,
angle-in-degrees is a D_floating number. For MTH$GSINCOSD,
angle-in-degrees is a G_floating number. For MTH$HSINCOSD,
angle-in-degrees is an H_floating number.
sine
VMS usage: floating_point
type: F_floating, D_floating, G_floating, H_floating
access: write only
mechanism: by reference
Sine of the angle specified by angle-in-degrees. The sine argument
is the address of a floating-point number. MTH$SINCOSD writes an
F_floating number into sine. MTH$DSINCOSD writes a D_floating
number into sine. MTH$GSINCOSD writes a G_floating number into
sine. MTH$HSINCOSD writes an H_floating number into sine.
cosine
VMS usage: floating_point
type: F_floating, D_floating, G_floating, H_floating
access: write only
mechanism: by reference
Cosine of the angle specified by angle-in-degrees. The cosine
argument is the address of a floating-point number. MTH$SINCOSD
writes an F_floating number into cosine. MTH$DSINCOSD writes a
D_floating number into cosine. MTH$GSINCOSD writes a G_floating
number into cosine. MTH$HSINCOSD writes an H_floating number into
cosine.
MTH$xSIND
The Sine of Angle Expressed in Degrees routine returns the sine of a
given angle (in degrees).
Format:
MTH$SIND angle-in-degrees
MTH$DSIND angle-in-degrees
MTH$GSIND angle-in-degrees
Each of the above formats accepts as input one of
the floating-point types.
Arguments:
angle-in-degrees
VMS usage: floating_point
type: F_floating, D_floating, G_floating
access: read only
mechanism: by reference
Angle (in degrees). The angle-in-degrees argument is the address of
a floating-point number that is this angle. For MTH$SIND,
angle-in-degrees specifies an F_floating number. For MTH$DSIND,
angle-in-degrees specifies a D_floating number. For MTH$GSIND,
angle-in-degrees specifies a G_floating number.
MTH$xSINH
The Hyperbolic Sine routine returns the hyperbolic sine of the input
value specified by floating-point-input-value.
Format:
MTH$SINH floating-point-input-value
MTH$DSINH floating-point-input-value
MTH$GSINH floating-point-input-value
Each of the above formats accepts as input one of
the floating-point types.
Arguments:
floating-point-input-value
VMS usage: floating_point
type: F_floating, D_floating, G_floating
access: read only
mechanism: by reference
The input value. The floating-point-input-value argument is the
address of a floating-point number that is this value. For
MTH$SINH, floating-point-input-value specifies an F_floating number.
For MTH$DSINH, floating-point-input-value specifies a D_floating
number. For MTH$GSINH, floating-point-input-value specifies a
G_floating number.
MTH$xSQRT
The Square Root routine returns the square root of the input value
floating-point-input-value.
Format:
MTH$SQRT floating-point-input-value
MTH$DSQRT floating-point-input-value
MTH$GSQRT floating-point-input-value
Each of the above formats accepts as input one of
the floating-point types.
Arguments:
floating-point-input-value
VMS usage: floating_point
type: F_floating, D_floating, G_floating
access: read only
mechanism: by reference
Input value. The floating-point-input-value argument is the address
of a floating-point number that contains this input value. For
MTH$SQRT, floating-point-input-value specifies an F_floating number.
For MTH$DSQRT, floating-point-input-value specifies a D_floating
number. For MTH$GSQRT, floating-point-input-value specifies a
G_floating number.
MTH$xTAN
The Tangent of Angle Expressed in Radians routine returns the
tangent of a given angle (in radians).
Format:
MTH$TAN angle-in-radians
MTH$DTAN angle-in-radians
MTH$GTAN angle-in-radians
Each of the above formats accepts as input one of
the floating-point types.
Arguments:
angle-in-radians
VMS usage: floating_point
type: F_floating, D_floating, G_floating
access: read only
mechanism: by reference
The input angle (in radians). The angle-in-radians argument is the
address of a floating-point number that is this angle. For MTH$TAN,
angle-in-radians specifies an F_floating number. For MTH$DTAN,
angle-in-radians specifies a D_floating number. For MTH$GTAN,
angle-in-radians specifies a G_floating number.
MTH$xTAND
The Tangent of Angle Expressed in Degrees routine returns the
tangent of a given angle (in degrees).
Format:
MTH$TAND angle-in-degrees
MTH$DTAND angle-in-degrees
MTH$GTAND angle-in-degrees
Each of the above formats accepts as input one of
the floating-point types.
Arguments:
angle-in-degrees
VMS usage: floating_point
type: F_floating, D_floating, G_floating
access: read only
mechanism: by reference
The input angle (in degrees). The angle-in-degrees argument is the
address of a floating-point number which is this angle. For
MTH$TAND, angle-in-degrees specifies an F_floating number. For
MTH$DTAND, angle-in-degrees specifies a D_floating number. For
MTH$GTAND, angle-in-degrees specifies a G_floating number.
MTH$xTANH
The Compute the Hyperbolic Tangent routine returns the hyperbolic
tangent of the input value.
Format:
MTH$TANH floating-point-input-value
MTH$DTANH floating-point-input-value
MTH$GTANH floating-point-input-value
Each of the above formats accepts as input one of
the floating-point types.
Arguments:
floating-point-input-value
VMS usage: floating_point
type: F_floating, D_floating, G_floating
access: read only
mechanism: by reference
The input value. The floating-point-input-value argument is the
address of a floating-point number that contains this input value.
For MTH$TANH, floating-point-input-value specifies an F_floating
number. For MTH$DTANH, floating-point-input-value specifies a
D_floating number. For MTH$GTANH, floating-point-input-value
specifies a G_floating number.
MTH$UMAX
The Compute Unsigned Maximum routine computes the unsigned longword
maximum of n unsigned longword arguments, where n is greater than or
equal to 1.
Format:
MTH$UMAX argument [argument,...]
Arguments:
argument
VMS usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
Argument whose maximum MTH$UMAX computes. Each argument argument is
an unsigned longword that contains one of these values.
argument
VMS usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
Additional arguments whose maximum MTH$UMAX computes. Each argument
argument is an unsigned longword that contains one of these values.
MTH$UMIN
The Compute Unsigned Minimum routine computes the unsigned longword
minimum of n unsigned longword arguments, where n is greater than or
equal to 1.
Format:
MTH$UMIN argument [argument,...]
Arguments:
argument
VMS usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
Argument whose minimum MTH$UMIN computes. Each argument argument is
an unsigned longword that contains one of these values.
argument
VMS usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
Additional arguments whose minimum MTH$UMIN computes. Each argument
argument is an unsigned longword that contains one of these values.
MTH$VxFOLRy MA V15
The First Order Linear Recurrence - Multiplication and Addition
routines provide a vectorized algorithm for the linear recurrence
relation that includes both multiplication and addition
operations.
Format
MTH$VJFOLRP_MA_V15 n,a,inca,b,incb,c,incc
MTH$VFFOLRP_MA_V15 n,a,inca,b,incb,c,incc
MTH$VDFOLRP_MA_V15 n,a,inca,b,incb,c,incc
MTH$VGFOLRP_MA_V15 n,a,inca,b,incb,c,incc
MTH$VJFOLRN_MA_V15 n,a,inca,b,incb,c,incc
MTH$VFFOLRN_MA_V15 n,a,inca,b,incb,c,incc
MTH$VDFOLRN_MA_V15 n,a,inca,b,incb,c,incc
MTH$VGFOLRN_MA_V15 n,a,inca,b,incb,c,incc
To obtain one of the preceding formats, substitute the
following for x and y in MTH$VxFOLRy_MA_V15:
x J for longword integer, F for F-floating, D for D-
floating, G for G-floating
y P for a positive recursion element, N for a negative
recursion element
Arguments
n
VMS Usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Length of the linear recurrence. The n argument is the address of
a signed longword integer containing the length.
a
VMS Usage: longword_signed or floating_point
type: longword integer (signed), F_floating, D_floating, or
G_floating
access: read only
mechanism: by reference, array reference
Array of length at least
1+(n-1)*inca
where:
n length of the linear recurrence specified in n
inca increment argument for the array a specified in inca
The a argument is the address of a longword integer or floating-
point that is this array.
inca
VMS Usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Increment argument for the array a. The inca argument is the
address of a signed longword integer containing the increment
argument. For contiguous elements, specify 1 for inca.
b
VMS Usage: longword_signed or floating_point
type: longword integer (signed), F_floating, D_floating, or
G_floating
access: read only
mechanism: by reference, array reference
Array of length at least
1+(n-1)*incb
where:
n length of the linear recurrence specified in n
incb increment argument for the array b specified in incb
The b argument is the address of a longword integer or floating-
point number that is this array.
incb
VMS Usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Increment argument for the array b. The incb argument is the
address of a signed longword integer containing the increment
argument. For contiguous elements, specify 1 for incb.
c
VMS Usage: longword_signed or floating_point
type: longword integer (signed), F_floating, D_floating, or
G_floating
access: modify
mechanism: by reference, array reference
Array of length at least
1+n*incc
where:
n length of the linear recurrence specified in n
incc increment argument for the array c specified in incc
The c argument is the address of a longword integer or floating-
point number that is this array.
incc
VMS Usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Increment argument for the array c. The incc argument is the
address of a signed longword integer containing the increment
argument. For contiguous elements, specify 1 for incc. Do not
specify 0 for incc.
MTH$VxFOLRy z V8
The First Order Linear Recurrence - Multiplication or Addition
routines provide a vectorized algorithm for the linear recurrence
relation that includes either a multiplication or an addition
operation, but not both.
Format
MTH$VJFOLRP_M_V8 n,a,inca,b,incb
MTH$VFFOLRP_M_V8 n,a,inca,b,incb
MTH$VDFOLRP_M_V8 n,a,inca,b,incb
MTH$VGFOLRP_M_V8 n,a,inca,b,incb
MTH$VJFOLRN_M_V8 n,a,inca,b,incb
MTH$VFFOLRN_M_V8 n,a,inca,b,incb
MTH$VDFOLRN_M_V8 n,a,inca,b,incb
MTH$VGFOLRN_M_V8 n,a,inca,b,incb
MTH$VJFOLRP_A_V8 n,a,inca,b,incb
MTH$VFFOLRP_A_V8 n,a,inca,b,incb
MTH$VDFOLRP_A_V8 n,a,inca,b,incb
MTH$VGFOLRP_A_V8 n,a,inca,b,incb
MTH$VJFOLRN_A_V8 n,a,inca,b,incb
MTH$VFFOLRN_A_V8 n,a,inca,b,incb
MTH$VDFOLRN_A_V8 n,a,inca,b,incb
MTH$VGFOLRN_A_V8 n,a,inca,b,incb
To obtain one of the preceding formats, substitute the
following for x, y, and z in MTH$VxFOLRy_z_V8:
x J for longword integer, F for F-floating, D for D-
floating, G for G-floating
y P for a positive recursion element, N for a negative
recursion element
z M for multiplication, A for addition
Arguments
n
VMS Usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Length of the linear recurrence. The n argument is the address of
a signed longword integer containing the length.
a
VMS Usage: longword_signed or floating_point
type: longword integer (signed), F_floating, D_floating, or
G_floating
access: read only
mechanism: by reference, array reference
Array of length at least
1+(n-1)*inca
where:
n length of the linear recurrence specified in n
inca increment argument for the array a specified in inca
The a argument is the address of a longword integer or floating-
point that is this array.
inca
VMS Usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Increment argument for the array a. The inca argument is the
address of a signed longword integer containing the increment
argument. For contiguous elements, specify 1 for inca.
b
VMS Usage: longword_signed or floating_point
type: longword integer (signed), F_floating, D_floating, or
G_floating
access: modify
mechanism: by reference, array reference
Array of length at least
1+(n-1)*incb
where:
n length of the linear recurrence specified in n
incb increment argument for the array b specified in incb
The b argument is the address of a longword integer or floating-
point number that is this array.
incb
VMS Usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Increment argument for the array b. The incb argument is the
address of a signed longword integer containing the increment
argument. For contiguous elements, specify 1 for incb.
MTH$VxFOLRLy MA V5
The First Order Linear Recurrence - Multiplication and Addition -
Last Value routines provide a vectorized algorithm for the linear
recurrence relation that includes both multiplication and addition
operations. Only the last value computed is stored.
Format
MTH$VJFOLRLP_MA_V5 n,a,inca,b,incb,t
MTH$VFFOLRLP_MA_V5 n,a,inca,b,incb,t
MTH$VDFOLRLP_MA_V5 n,a,inca,b,incb,t
MTH$VGFOLRLP_MA_V5 n,a,inca,b,incb,t
MTH$VJFOLRLN_MA_V5 n,a,inca,b,incb,t
MTH$VFFOLRLN_MA_V5 n,a,inca,b,incb,t
MTH$VDFOLRLN_MA_V5 n,a,inca,b,incb,t
MTH$VGFOLRLN_MA_V5 n,a,inca,b,incb,t
To obtain one of the preceding formats, substitute the
following for x and y in MTH$VxFOLRLy_MA_V5:
x J for longword integer, F for F-floating, D for D-
floating, G for G-floating
y P for a positive recursion element, N for a negative
recursion element
Arguments
n
VMS Usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Length of the linear recurrence. The n argument is the address of
a signed longword integer containing the length.
a
VMS Usage: longword_signed or floating_point
type: longword integer (signed), F_floating, D_floating, or
G_floating
access: read only
mechanism: by reference, array reference
Array of length at least
1+(n-1)*inca
where:
n length of the linear recurrence specified in n
inca increment argument for the array a specified in inca
The a argument is the address of a longword integer or floating-
point that is this array.
inca
VMS Usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Increment argument for the array a. The inca argument is the
address of a signed longword integer containing the increment
argument. For contiguous elements, specify 1 for inca.
b
VMS Usage: longword_signed or floating_point
type: longword integer (signed), F_floating, D_floating, or
G_floating
access: read only
mechanism: by reference, array reference
Array of length at least
1+(n-1)*incb
where:
n length of the linear recurrence specified in n
incb increment argument for the array b specified in incb
The b argument is the address of a longword integer or floating-
point number that is this array.
incb
VMS Usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Increment argument for the array b. The incb argument is the
address of a signed longword integer containing the increment
argument. For contiguous elements, specify 1 for incb.
t
VMS Usage: longword_signed or floating_point
type: longword integer (signed), F_floating, D_floating, or
G_floating
access: modify
mechanism: by reference
Variable containing the starting value for the recurrence;
overwritten with the value computed by the last iteration of the
linear recurrence relation. The t argument is the address of a
longword integer or floating-point number that is this value.
MTH$VxFOLRLy z V2
The First Order Linear Recurrence - Multiplication or Addition -
Last Value routines provide a vectorized algorithm for the linear
recurrence relation that includes either a multiplication or an
addition operation. Only the last value computed is stored.
Format
MTH$VJFOLRLP_M_V2 n,a,inca,t
MTH$VFFOLRLP_M_V2 n,a,inca,t
MTH$VDFOLRLP_M_V2 n,a,inca,t
MTH$VGFOLRLP_M_V2 n,a,inca,t
MTH$VJFOLRLN_M_V2 n,a,inca,t
MTH$VFFOLRLN_M_V2 n,a,inca,t
MTH$VDFOLRLN_M_V2 n,a,inca,t
MTH$VGFOLRLN_M_V2 n,a,inca,t
MTH$VJFOLRLP_A_V2 n,a,inca,t
MTH$VFFOLRLP_A_V2 n,a,inca,t
MTH$VDFOLRLP_A_V2 n,a,inca,t
MTH$VGFOLRLP_A_V2 n,a,inca,t
MTH$VJFOLRLN_A_V2 n,a,inca,t
MTH$VFFOLRLN_A_V2 n,a,inca,t
MTH$VDFOLRLN_A_V2 n,a,inca,t
MTH$VGFOLRLN_A_V2 n,a,inca,t
To obtain one of the preceding formats, substitute the
following for x, y, and z in MTH$VxFOLRLy_z_V2:
x J for longword integer, F for F-floating, D for D-
floating, G for G-floating
y P for a positive recursion element, N for a negative
recursion element
z M for multiplication, A for addition
Arguments
n
VMS Usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Length of the linear recurrence. The n argument is the address of
a signed longword integer containing the length.
a
VMS Usage: longword_signed or floating_point
type: longword integer (signed), F_floating, D_floating, or
G_floating
access: read only
mechanism: by reference, array reference
Array of length at least
n*inca
where:
n length of the linear recurrence specified in n
inca increment argument for the array a specified in inca
The a argument is the address of a longword integer or floating-
point that is this array.
inca
VMS Usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Increment argument for the array a. The inca argument is the
address of a signed longword integer containing the increment
argument. For contiguous elements, specify 1 for inca.
t
VMS Usage: longword_signed or floating_point
type: longword integer (signed), F_floating, D_floating, or
G_floating
access: modify
mechanism: by reference
Variable containing the starting value for the recurrence;
overwritten with the value computed by the last iteration of the
linear recurrence relation. The t argument is the address of a
longword integer or floating-point number that is this value.
MTH$VxFOLRLy z V2
The First Order Linear Recurrence - Multiplication or Addition -
Last Value routines provide a vectorized algorithm for the linear
recurrence relation that includes either a multiplication or an
addition operation. Only the last value computed is stored.
Format
MTH$VJFOLRLP_M_V2 n,a,inca,t
MTH$VFFOLRLP_M_V2 n,a,inca,t
MTH$VDFOLRLP_M_V2 n,a,inca,t
MTH$VGFOLRLP_M_V2 n,a,inca,t
MTH$VJFOLRLN_M_V2 n,a,inca,t
MTH$VFFOLRLN_M_V2 n,a,inca,t
MTH$VDFOLRLN_M_V2 n,a,inca,t
MTH$VGFOLRLN_M_V2 n,a,inca,t
MTH$VJFOLRLP_A_V2 n,a,inca,t
MTH$VFFOLRLP_A_V2 n,a,inca,t
MTH$VDFOLRLP_A_V2 n,a,inca,t
MTH$VGFOLRLP_A_V2 n,a,inca,t
MTH$VJFOLRLN_A_V2 n,a,inca,t
MTH$VFFOLRLN_A_V2 n,a,inca,t
MTH$VDFOLRLN_A_V2 n,a,inca,t
MTH$VGFOLRLN_A_V2 n,a,inca,t
To obtain one of the preceding formats, substitute the
following for x, y, and z in MTH$VxFOLRLy_z_V2:
x J for longword integer, F for F-floating, D for D-
floating, G for G-floating
y P for a positive recursion element, N for a negative
recursion element
z M for multiplication, A for addition
Arguments
n
VMS Usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Length of the linear recurrence. The n argument is the address of
a signed longword integer containing the length.
a
VMS Usage: longword_signed or floating_point
type: longword integer (signed), F_floating, D_floating, or
G_floating
access: read only
mechanism: by reference, array reference
Array of length at least
n*inca
where:
n length of the linear recurrence specified in n
inca increment argument for the array a specified in inca
The a argument is the address of a longword integer or floating-
point that is this array.
inca
VMS Usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Increment argument for the array a. The inca argument is the
address of a signed longword integer containing the increment
argument. For contiguous elements, specify 1 for inca.
t
VMS Usage: longword_signed or floating_point
type: longword integer (signed), F_floating, D_floating, or
G_floating
access: modify
mechanism: by reference
Variable containing the starting value for the recurrence;
overwritten with the value computed by the last iteration of the
linear recurrence relation. The t argument is the address of a
longword integer or floating-point number that is this value.
OTS$
Additional information available:
OTS$CNVOUTOTS$CVT_L_TBOTS$CVT_L_TIOTS$CVT_L_TL
OTS$CVT_L_TOOTS$CVT_L_TUOTS$CVT_L_TZOTS$CVT_TB_L
OTS$CVT_TI_LOTS$CVT_TL_LOTS$CVT_TO_LOTS$CVT_TU_L
OTS$CVT_TZ_LOTS$DIV_PK_LONGOTS$DIV_PK_SHORTOTS$MOVE3
OTS$MOVE5OTS$POWDDOTS$POWDJOTS$POWDR
OTS$POWGGOTS$POWGJOTS$POWHH_R3OTS$POWHJ_R3
OTS$POWIIOTS$POWJJOTS$POWLULUOTS$POWRD
OTS$POWRJOTS$POWRROTS$SCOPY_DXDXOTS$SCOPY_R_DX
OTS$SFREE1_DDOTS$SFREEN_DDOTS$SGET1_DD
OTS$CVT T zOTS$CVT T zOTS$DIVCxOTS$MULCx
OTS$POWCxCxOTS$POWCxJOTS$POWxLU
OTS$CNVOUT
The Convert Floating to Character String routines convert a
D_floating, G_floating or H_floating number to a character string in
the FORTRAN E format.
Format:
OTS$CNVOUT D-G-or-H-float-pt-input-val
,fixed-length-resultant-string ,digits-in-fraction
OTS$CNVOUT_G D-G-or-H-float-pt-input-val
,fixed-length-resultant-string ,digits-in-fraction
OTS$CNVOUT_H D-G-or-H-float-pt-input-val
,fixed-length-resultant-string ,digits-in-fraction
Arguments:
D-G-or-H-float-pt-input-val
VMS usage: floating_point
type: D_floating, G_floating, H_floating
access: read only
mechanism: by reference
Value that OTS$CNVOUT converts to a character string. For
OTS$CNVOUT, the D-G-or-H-float-pt-input-val argument is the address
of a D_floating number containing the value. For OTS$CNVOUT_G, the
D-G-or-H-float-pt-input-val argument is the address of a G_floating
number containing the value. For OTS$CNVOUT_H, the
D-G-or-H-float-pt-input-val argument is the address of an H_floating
number containing the value.
fixed-length-resultant-string
VMS usage: char_string
type: character string
access: write only
mechanism: by descriptor, fixed length
Output string into which OTS$CNVOUT writes the character string
result of the conversion. The fixed-length-resultant-string
argument is the address of a descriptor pointing to the output
string.
digits-in-fraction
VMS usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by value
Number of digits in the fractional portion of the result. The
digits-in-fraction argument is an unsigned longword containing the
number of digits to be written to the fractional portion of the
result.
OTS$CVT_L_TB
The Convert an Unsigned Integer to Binary Text routine converts an
unsigned integer value of arbitrary length to binary representation
in an ASCII text string. By default, a longword is converted.
Format:
OTS$CVT_L_TB varying-input-value ,fixed-length-resultant-string
[,number-of-digits] [,input-value-size]
Arguments:
varying-input-value
VMS usage: varying_arg
type: unspecified
access: read only
mechanism: by reference
Unsigned integer value that OTS$CVT_L_TB converts to binary
representation in an ASCII text string. The varying-input-value
argument is the address of this integer value.
fixed-length-resultant-string
VMS usage: char_string
type: character string
access: write only
mechanism: by descriptor, fixed-length
ASCII text string that OTS$CVT_L_TB creates when it converts the
integer value. The fixed-length-resultant-string argument is the
address of a descriptor pointing to this ASCII text string. The
string is assumed to be fixed length (DSC$K_CLASS_S).
number-of-digits
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by value
Minimum number of digits in the binary representation to be
generated. The number-of-digits argument is a signed longword
integer containing this minumum number. This is an optional
argument. If omitted, the default is 1. If the actual number of
significant digits is less than the minimum number of digits,
leading zeros are produced. If the minimum number of digits is zero
and the value of the integer to be converted is also zero,
OTS$CVT_L_TB creates a blank string.
input-value-size
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by value
Size of the integer to be converted, in bytes. The input-value-size
argument is a signed longword integer containing the byte size.
This is an optional argument. If omitted, the default is 4.
OTS$CVT_L_TI
The Convert Signed Integer to Decimal Text routine converts a signed
integer to a decimal ASCII text string. This procedure supports
FORTRAN Iw and Iw.m output and BASIC output conversion.
Format:
OTS$CVT_L_TI varying-input-value ,fixed-length-resultant-string
[,number-of-digits] [,input-value-size] [,flags-value]
Arguments:
varying-input-value
VMS usage: varying_arg
type: unspecified
access: read only
mechanism: by reference
Signed integer value that OTS$CVT_L_TI converts to a decimal ASCII
text string. The varying-input-value argument is the address of
this integer value.
fixed-length-resultant-string
VMS usage: char_string
type: character string
access: write only
mechanism: by descriptor, fixed length
Decimal ASCII text string that OTS$CVT_L_TI creates when it converts
the signed integer. The fixed-length-resultant-string argument is
the address of a descriptor pointing to this text string. The
string is assumed to be fixed-length (DSC$K_CLASS_S).
number-of-digits
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by value
Minimum number of digits to be generated when OTS$CVT_L_TI converts
the signed integer to a decimal ASCII text string. The
number-of-digits argument is a signed longword integer containing
this number. This is an optional argument. If omitted, the default
value is 1. If the actual number of significant digits is smaller,
OTS$CVT_L_TI inserts leading zeros into the output string. If
number-of-digits is zero and varying-input-value is zero,
OTS$CVT_L_TI writes a blank string to the output string.
input-value-size
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by value
Number of bytes occupied by the value to be converted to text. The
input-value-size argument is a signed longword integer containing
this value size. The value size must be either 1, 2, or 4. If
value size is 1 or 2, the value is sign-extended to a longword
before conversion. This is an optional argument. If omitted, the
default is 4.
flags-value
VMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by value
Caller-supplied flags that you may use if you want OTS$CVT_L_TI to
insert a plus sign before the converted number. The flags-value
argument is an unsigned longword containing the flags.
OTS$CVT_L_TL
The Convert Integer to Logical Text routine converts an integer to
ASCII text string representation using FORTRAN L (logical) format.
Format:
OTS$CVT_L_TL longword-integer-value
,fixed-length-resultant-string
Arguments:
longword-integer-value
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Value that OTS$CVT_L_TL converts to an ASCII text string. The
longword-integer-value argument is the address of a signed longword
integer containing this integer value.
fixed-length-resultant-string
VMS usage: char_string
type: character string
access: write only
mechanism: by descriptor, fixed length
Output string that OTS$CVT_L_TL creates when it converts the integer
value to an ASCII text string. The fixed-length-resultant-string
argument is the address of a descriptor pointing to this ASCII text
string.
OTS$CVT_L_TO
The Convert Unsigned Integer to Octal Text routine converts an
unsigned integer to an octal ASCII text string. OTS$CVT_L_TO
supports FORTRAN Ow and Ow.m output conversion formats.
Format:
OTS$CVT_L_TO varying-input-value ,fixed-length-resultant-string
[,number-of-digits] [,input-value-size]
Arguments:
varying-input-value
VMS usage: varying_arg
type: unspecified
access: read only
mechanism: by reference
Integer value that OTS$CVT_L_TO converts to an octal ASCII text
string. The varying-input-value argument is the address of this
integer value.
fixed-length-resultant-string
VMS usage: char_string
type: character string
access: write only
mechanism: by descriptor, fixed length
Output string that OTS$CVT_L_TO creates when it converts the integer
value to an octal ASCII text string. The
fixed-length-resultant-string argument is the address of a
descriptor pointing to the octal ASCII text string. The string is
assumed to be fixed-length (DSC$K_CLASS_S).
number-of-digits
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by value
Minimum number of digits that OTS$CVT_L_TO generates when it
converts the integer value to an octal ASCII text string. The
number-of-digits argument is a signed longword integer containing
the minimum number of digits. This is an optional argument. If
omitted, the default is 1. If the actual number of significant
digits in the octal ASCII text string is less than the minimum
number of digits, OTS$CVT_L_TO inserts leading zeros into the output
string. If number-of-digits is zero and varying-input-value is
zero, OTS$CVT_L_TO writes a blank string to the output string.
input-value-size
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by value
Size of the integer to be converted, in bytes. The input-value-size
argument is a signed longword integer containing the number of bytes
in the integer to be converted by OTS$CVT_L_TO. This is an optional
argument. If omitted, the default is 4.
OTS$CVT_L_TU
The Convert Unsigned Integer to Decimal Text routine converts a
byte, word or longword value to unsigned decimal representation in
an ASCII text string. By default, a longword is converted.
Format:
OTS$CVT_L_TU varying-input-value ,fixed-length-resultant-string
[,number-of-digits] [,input-value-size]
Arguments:
varying-input-value
VMS usage: varying_arg
type: unspecified
access: read only
mechanism: by reference
Unsigned byte, word or longword that OTS$CVT_L_TU converts to
unsigned decimal representation in an ASCII text string. (The value
of the input-value-size argument determines whether
varying-input-value is a byte, word or longword.) The
varying-input-value argument is the address of the unsigned integer.
fixed-length-resultant-string
VMS usage: char_string
type: character string
access: write only
mechanism: by descriptor, fixed-length
Output string (fixed-length) that OTS$CVT_L_TU creates when it
converts the integer value to unsigned decimal representation in an
ASCII text string. The fixed-length-resultant-string argument is
the address of a descriptor pointing to this ASCII text string.
number-of-digits
VMS usage: longword_signed
type: longword (signed)
access: read only
mechanism: by value
Minimum number of digits in the ASCII text string that OTS$CVT_L_TU
creates. The number-of-digits argument is an unsigned longword
containing the minimum number. This is an optional argument. If
omitted, the default is 1.
input-value-size
VMS usage: longword_signed
type: longword (signed)
access: read only
mechanism: by value
Size of the integer value to be converted, in bytes. The
input-value-size argument is an unsigned longword containing the
size of the integer value. This is an optional argument. If
omitted, the default is 4. The only values that OTS$CVT_L_TU allows
are 1, 2 and 4. If any other value is specified, OTS$CVT_L_TU uses
the default value, 4.
OTS$CVT_L_TZ
The Convert Integer to Hexadecimal Text routine converts an unsigned
integer to a hexadecimal ASCII text string. OTS$CVT_L_TZ supports
FORTRAN Zw and Zw.m output conversion formats.
Format:
OTS$CVT_L_TZ varying-input-value ,fixed-length-resultant-string
[,number-of-digits] [,input-value-size]
Arguments:
varying-input-value
VMS usage: varying_arg
type: unspecified
access: read only
mechanism: by reference
Integer value that OTS$CVT_L_TZ converts to a hexadecimal ASCII text
string. The varying-input-value argument is the address of this
integer value.
fixed-length-resultant-string
VMS usage: char_string
type: character string
access: write only
mechanism: by descriptor, fixed length
Output string that OTS$CVT_L_TZ creates when it converts the integer
value to a hexidecimal ASCII text string. The
fixed-length-resultant-string argument is the address of a
descriptor pointing to this ASCII text string. The string is
assumed to be fixed-length (DSC$K_CLASS_S).
number-of-digits
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by value
Minimum number of digits in the ASCII text string that OTS$CVT_L_TZ
creates when it converts the integer. The number-of-digits argument
is a signed longword integer containing this minimum number. This
is an optional argument. If omitted, the default is 1. If the
actual number of significant digits in the text string that
OTS$CVT_L_TZ creates is less than this minimum number, OTS$CVT_L_TZ
inserts leading zeros in the output string. If the minimum number
of digits is zero and the integer value to be converted is also
zero, OTS$CVT_L_TZ writes a blank string to the output string.
input-value-size
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by value
Size of the integer that OTS$CVT_L_TZ converts, in bytes. The
input-value-size argument is a signed longword integer containing
the value size. This is an optional argument. If omitted, the
default is 4.
OTS$CVT_TB_L
The Convert Binary Text to Unsigned Integer routine converts an
ASCII text string representation of an unsigned binary value to an
unsigned integer value of arbitrary length. By default, the result
is a longword. Valid input characters are the blank and the digits
0 and 1. No sign is permitted.
Format:
OTS$CVT_TB_L input-string ,varying-output-value
[,output-value-size] [,flags-value]
Arguments:
input-string
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
Input string containing the ASCII text string representation of an
unsigned binary value that OTS$CVT_TB_L converts to an integer
value. The input-string argument is the address of a descriptor
pointing to the ASCII text string.
varying-output-value
VMS usage: varying_arg
type: unspecified
access: write only
mechanism: by reference
Integer that OTS$CVT_TB_L creates when it converts the ASCII text
string. The varying-output-value argument is the address of the
integer value.
output-value-size
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by value
Number of bytes occupied by the value created when OTS$CVT_TB_L
converts the ASCII text string to an integer value. The
output-value-size argument contains the value size. If
output-value-size contains a zero or a negative number, OTS$CVT_TB_L
returns an error code as the condition value. This is an optional
argument. If omitted, the default is 4.
flags-value
VMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by value
User-supplied flags that OTS$CVT_TB_L uses to determine how to
interpret blanks and tabs. The flags-value argument contains the
value of the user-supplied flags.
OTS$CVT_TI_L
The Convert Signed Integer Text to Integer routine converts an ASCII
text string representation of a decimal number to a signed byte,
word, or longword integer value. The result is a longword by
default, but the calling program can specify a byte or a word value
instead.
Format:
OTS$CVT_TI_L fixed-or-dynamic-input-string ,varying-output-value
[,output-value-size] [,flags-value]
Arguments:
fixed-or-dynamic-input-string
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor, fixed-length or dynamic string
Input ACSII text string that OTS$CVT_TI_L converts to a signed byte,
word, or longword. The fixed-or-dynamic-input-string argument is
the address of a descriptor pointing to the input string.
varying-output-value
VMS usage: varying_arg
type: unspecified
access: write only
mechanism: by reference
Signed byte, word, or longword integer value (depending on
input-value-size) that OTS$CVT_TI_L creates when it converts the
ASCII text string. The varying-output-value argument is the address
of the integer value.
output-value-size
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by value
Number of bytes occupied by the value that OTS$CVT_TI_L creates when
it converts the ASCII text string to an integer value. Valid values
for the output-value-size argument are 1, 2, and 4. The contents of
output-value-size determine whether the integer value that
OTS$CVT_TI_L creates is a byte, word, or longword. If an invalid
value is given, OTS$CVT_TI_L returns an error. This is an optional
argument. If omitted, the default is 4 and OTS$CVT_TI_L returns a
longword integer.
flags-value
VMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by value
User-supplied flags that OTS$CVT_TI_L uses to determine how blanks
and tabs are interpreted. The flags-value argument is an unsigned
longword containing the value of the flags.
Bit Description
0 If set, OTS$CVT_TI_L ignores all blanks. If clear,
OTS$CVT_TI_L ignores leading blanks but interprets
blanks after the first legal character as zeros.
4 If set, OTS$CVT_TI_L ignores tabs. If clear,
OTS$CVT_TI_L interprets tabs as invalid characters.
OTS$CVT_TL_L
The Convert Logical Text to Integer routine converts an ASCII text
string representation of a FORTRAN-77 L format to a byte, word, or
longword integer value. The result is a longword by default, but
the calling program can specify a byte or a word value instead.
Format:
OTS$CVT_TL_L fixed-or-dynamic-input-string
,varying-output-value [,output-value-size]
Arguments:
fixed-or-dynamic-input-string
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor, fixed-length or dynamic string
Input string containing an ASCII text representation of a FORTRAN-77
L format that OTS$CVT_TL_L converts to a byte, word or longword
integer value. The fixed-or-dynamic-input-string argument is the
address of a descriptor pointing to the input string.
varying-output-value
VMS usage: varying_arg
type: unspecified
access: write only
mechanism: by reference
Integer value that OTS$CVT_TL_L creates when it converts the ACSII
text input string. The varying-output-value argument is the address
of this integer value. OTS$CVT_TL_L returns a minus one (-1) as the
contents of the varying-output-value argument if the character
denoted by "Letter:" is "T" or "t". Otherwise, OTS$CVT_TL_L sets
varying-output-value to zero.
output-value-size
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by value
Number of bytes occupied by the integer value that OTS$CVT_TL_L
creates when it converts the ASCII text input string. The
output-value-size argument contains the number of bytes. Valid
values are 1, 2, and 4. These values determine whether OTS$CVT_TL_L
returns a byte, word or longword integer value. If an invalid value
is given, OTS$CVT_TL_L returns an error. This is an optional
argument. If omitted, the default is 4 and OTS$CVT_TL_L returns a
longword integer value.
OTS$CVT_TO_L
The Convert Octal Text to Signed Integer routine converts an ASCII
text string representation of an unsigned octal value to an unsigned
integer of an arbitrary length. The result is a longword by
default, but the calling program can specify any number of bytes.
Format:
OTS$CVT_TO_L fixed-or-dynamic-input-string
,varying-output-value [,output-value-size]
[,flags-value]
Arguments:
fixed-or-dynamic-input-string
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor, fixed-length or dynamic string
Input string containing an ASCII text string representation of an
unsigned octal value that OTS$CVT_TO_L converts to an unsigned
integer. The fixed-or-dynamic-input-string argument is the address
of a descriptor pointing to the input string. The valid input
characters are blanks and the digits 0 through 7. No sign is
permitted.
varying-output-value
VMS usage: varying_arg
type: unspecified
access: write only
mechanism: by reference
Integer value that OTS$CVT_TO_L creates when it converts the input
string. The varying-output-value argument is the address of the
unsigned integer value.
output-value-size
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by value
Number of bytes occupied by the unsigned integer value. The
input-value-size argument contains the number of bytes. If the
content of the output-value-size argument is zero or a negative
number, OTS$CVT_TO_L returns an error. This is an optional
argument. If omitted, the default is 4 and OTS$CVT_TO_L returns a
longword integer.
flags-value
VMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by value
User-supplied flags that OTS$CVT_TO_L uses to determine how blanks
within the input string are interpreted. The flags-value argument
contains the user-supplied flags.
Bit 0 If set, OTS$CVT_TO_L ignores all blanks. If clear,
OTS$CVT_TO_L interprets blanks as zeros.
OTS$CVT_TU_L
The Convert Unsigned Decimal Text to Integer routine converts an
ASCII text string representation of an unsigned decimal value to an
unsigned byte, word, or longword value. By default, the result is a
longword. Valid input characters are the space and the digits 0
through 9. No sign is permitted.
Format:
OTS$CVT_TU_L fixed-length-input-string ,varying-output-value
[,output-value-size] [,flags-value]
Arguments:
fixed-length-input-string
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor, fixed-length
Input string (fixed-length) containing an ASCII text string
representation of an unsigned decimal value that OTS$CVT_TU_L
converts to a byte, word, or longword value. The
fixed-length-input-string argument is the address of a descriptor
pointing to the input string.
varying-output-value
VMS usage: varying_arg
type: unspecified
access: write only
mechanism: by reference
Byte, word, or longword (depending on output-value-size) into which
OTS$CVT_TU_L writes the converted value. The varying-output-value
argument is the address of the byte, word, or longword.
output-value-size
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by value
Number of bytes occupied by the value created when OTS$CVT_TU_L
converts the input string. The output-value-size argument contains
the number of bytes. OTS$CVT_TU_L allows value sizes of 1, 2 and 4.
If any other value is specified, or if input-value-size is omitted,
OTS$CVT_TU_L uses the default, 4.
flags-value
VMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by value
User-supplied flags which OTS$CVT_TU_L uses to determine how blanks
and tabs are interpreted. The flags-value argument contains the
user-supplied flags.
Bit Description
0 If set, OTS$CVT_TU_L ignores blanks. If clear,
OTS$CVT_TU_L interprets blanks as zeros.
4 If set, OTS$CVT_TU_L ignores tabs. If clear, OTS$CVT_TU_L
interprets tabs as invalid characters.
OTS$CVT T z
The Convert Numeric Text to D- or F-Floating routines convert an
ASCII text string representation of a numeric value to a D_floating
or F_floating value.
Format:
OTS$CVT_T_D fixed-or-dynamic-input-string
,floating-point-value [,digits-in-fraction]
[,scale-factor] [,flags-value] [,extension-bits]
OTS$CVT_T_F fixed-or-dynamic-input-string
,floating-point-value [,digits-in-fraction]
[,scale-factor] [,flags-value] [,extension-bits]
Each of the above formats corresponds to one of the
floating-point types.
Arguments:
fixed-or-dynamic-input-string
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor, fixed-length or dynamic string
Input string containing an ASCII text string representation of a
numeric value that OTS$CVT_T_Z converts to a D_floating or
F_floating value. The fixed-or-dynamic-input-string argument is the
address of a descriptor pointing to the input string.
floating-point-value
VMS usage: floating_point
type: D_floating, F_floating
access: write only
mechanism: by reference
Floating-point value that OTS$CVT_T_z creates when it converts the
input string. The floating-point-value argument is the address of
the floating-point value. For OTS$CVT_T_D, floating-point-value is
a D_floating number. For OTS$CVT_T_F, floating-point-value is an
F_floating number.
digits-in-fraction
VMS usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by value
Number of digits in the fraction if no decimal point is included in
the input string. The digits-in-fraction argument contains the
number of digits. This is an optional argument. If omitted, the
default is zero.
scale-factor
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by value
Scale factor. The scale-factor argument contains the value of the
scale factor. If bit 6 of the flags-value argument is clear, the
resultant value is divided by 10**factor unless the exponent is
present. If bit 6 of flags-value is set, the scale factor is always
applied. This is an optional argument. If omitted, the default is
zero.
flags-value
VMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by value
User-supplied flags. The flags-value argument contains the
user-supplied flags.
Bit 0 If set, OTS$CVT_T_z ignores blanks. If clear,
OTS$CVT_T_z interprets blanks as zeros.
Bit 1 If set, OTS$CVT_T_z allows only E or e exponents. If
clear, OTS$CVT_T_z allows E, e, D, d, Q and q
exponents. (Bit 1 is clear for BASIC and set for
FORTRAN.)
Bit 2 If set, OTS$CVT_T_z interprets an underflow as an
error. If clear, OTS$CVT_T_z does not interpret an
underflow as an error.
Bit 3 If set, OTS$CVT_T_z truncates the value. If clear,
OTS$CVT_T-z rounds the value.
Bit 4 If set, OTS$CVT_T_z ignores tabs. If clear, OTS$CVT_T_z
interprets tabs as invalid characters.
Bit 5 If set, an exponent must begin with a valid exponent
letter. If clear, the exponent letter may be omitted.
Bit 6 If set, OTS$CVT_T_z always applies the scale factor. If
clear, OTS$CVT_T_z applies the scale factor only if
there is no exponent present in the string.
extension-bits
VMS usage: byte_signed
type: byte (signed)
access: write only
mechanism: by reference
Extra precision bits. The extension-bits argument is the address of
a byte containing the extra precision bits. If present,
floating-point-value is not rounded, and the first n bits after
truncation are returned in this argument. For D_floating and
F_floating, n equals 8 and the bits are returned as a byte.
OTS$CVT T z
The Convert Numeric Text to G- or H-Floating routines convert an
ASCII text string representation of a numeric value to a G_floating
or H_floating value.
Format:
OTS$CVT_T_G fixed-or-dynamic-input-string
,floating-point-value [,digits-in-fraction]
[,scale-factor] [,flags-value] [,extension-bits]
OTS$CVT_T_H fixed-or-dynamic-input-string
,floating-point-value [,digits-in-fraction]
[,scale-factor] [,flags-value] [,extension-bits]
Each of the above formats corresponds to one of the
floating-point types.
Arguments:
fixed-or-dynamic-input-string
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor, fixed-length or dynamic string
Input string containing an ASCII text string representation of a
numeric value that OTS$CVT_T_Z converts to a G-floating or
H-floating value. The fixed-or-dynamic-input-string argument is the
address of a descriptor pointing to the input string.
floating-point-value
VMS usage: floating_point
type: G_floating, H_floating
access: write only
mechanism: by reference
Floating-point value that OTS$CVT_T_z creates when it converts the
input string. The floating-point-value argument is the address of
the floating-point value. For OTS$CVT_T_G, floating-point-value is
a G_floating number. For OTS$CVT_T_H, floating-point-value is an
H_floating number.
digits-in-fraction
VMS usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by value
Number of digits in the fraction if no decimal point is included in
the input string. The digits-in-fraction argument contains the
number of digits. This is an optional argument. If omitted, the
default is zero.
scale-factor
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by value
Scale factor. The scale-factor argument contains the value of the
scale factor. If bit 6 of the flags-value argument is clear, the
resultant value is divided by 10**factor unless the exponent is
present. If bit 6 of flags-value is set, the scale factor is always
applied. This is an optional argument. If omitted, the default is
zero.
flags-value
VMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by value
User-supplied flags. The flags-value argument contains the
user-supplied flags.
Bit 0 If set, OTS$CVT_T_z ignores blanks. If clear,
OTS$CVT_T_z interprets blanks as zeros.
Bit 1 If set, OTS$CVT_T_z allows only E or e exponents. If
clear, OTS$CVT_T_z allows E, e, D, d, Q and q
exponents. (Bit 1 is clear for BASIC and set for
FORTRAN.)
Bit 2 If set, OTS$CVT_T_z interprets an underflow as an
error. If clear, OTS$CVT_T_z does not interpret an
underflow as an error.
Bit 3 If set, OTS$CVT_T_z truncates the value. If clear,
OTS$CVT_T-z rounds the value.
Bit 4 If set, OTS$CVT_T_z ignores tabs. If clear, OTS$CVT_T_z
interprets tabs as invalid characters.
Bit 5 If set, an exponent must begin with a valid exponent
letter. If clear, the exponent letter may be omitted.
Bit 6 If set, OTS$CVT_T_z always applies the scale factor. If
clear, OTS$CVT_T_z applies the scale factor only if
there is no exponent present in the string.
extension-bits
VMS usage: word_signed
type: word integer (signed)
access: write only
mechanism: by reference
Extra precision bits. The extension-bits argument is the address of
a signed word integer containing the extra precision bits. If
present, floating-point-value is not rounded, and the first n bits
after truncation are returned in this argument. For G_floating and
H_floating, n equals 11 and 15, respectively, and the bits are
returned as a word, left-justified.
OTS$CVT_TZ_L
The Convert Hexadecimal Text to Unsigned Integer routine converts an
ASCII text string representation of an unsigned hexadecimal value to
an unsigned integer of an arbitrary length. The result is a
longword by default, but the calling program can specify either 1, 2
or 4 bytes to receive either a byte, word, or longword value.
Format:
OTS$CVT_TZ_L fixed-or-dynamic-input-string ,varying-input-value
[,input-value-size] [,flags-value]
Arguments:
fixed-or-dynamic-input-string
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor, fixed-length or dynamic string
Input string containing an ASCII text string representation of an
unsigned hexadecimal value that OTS$CVT_TZ_L converts to an unsigned
integer. The fixed-or-dynamic-input-string argument is the address
of a descriptor pointing to the input string. Valid input
characters are the space, the digits 0 through 9, and the letters A
through F. No sign is permitted. Lowercase letters a through f are
acceptable.
varying-input-value
VMS usage: varying_arg
type: unspecified
access: write only
mechanism: by reference
Integer value created when OTS$CVT_TZ_L converts the input string.
The varying-input-value argument is the address of the integer
value.
input-value-size
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by value
Number of bytes occupied by the integer value. The input-value-size
argument contains the number of bytes. If the value size is zero or
a negative number, OTS$CVT_TZ_L returns an input conversion error.
This is an optional argument. If omitted, the default is 4.
flags-value
VMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by value
User-supplied flags that OTS$CVT_TZ_L uses to determine how blanks
are interpreted. The flags-value argument is an unsigned longword
containing these user-supplied flags.
Bit 0 If set, OTS$CVT_TZ_L ignores blanks. If set,
OTS$CVT_TZ_L interprets blanks as zeros.
OTS$DIVCx
The Complex Division routines return a complex result of a complex
division on complex numbers.
Format:
OTS$DIVC complex-dividend ,complex-divisor
OTS$DIVCD_R3 complex-dividend ,complex-divisor
OTS$DIVCG_R3 complex-dividend ,complex-divisor
Each of the above three formats corresponds to one
of the three floating-point complex types.
Arguments:
complex-dividend
VMS usage: complex_number
type: F_floating complex, D_floating complex, G_floating complex
access: read only
mechanism: by value
Complex dividend. The complex-dividend argument contains a
floating-point complex value. For OTS$DIVC, complex-dividend is an
F_floating complex number. For OTS$DIVCD_R3, complex-dividend is a
D_floating complex number. For OTS$DIVCG_R3, complex-dividend is a
G_floating complex number.
complex-divisor
VMS usage: complex_number
type: F_floating complex, D_floating complex, G_floating complex
access: read only
mechanism: by value
Complex divisor. The complex-divisor argument contains the value of
the divisor. For OTS$DIVC, complex-divisor is an F_floating complex
number. For OTS$DIVCD_R3, complex-divisor is a D_floating complex
number. For OTS$DIVCG_R3, complex-divisor is a G_floating complex
number.
OTS$DIV_PK_LONG
The Packed Decimal Division with Long Divisor routine divides
fixed-point decimal data, which is stored in packed decimal form,
when precision and scale requirements for the quotient call for
multiple precision division. The divisor must have a precision of
thirty or thirty-one digits.
Format:
OTS$DIV_PK_LONG packed-decimal-dividend ,packed-decimal-divisor
,divisor-precision ,packed-decimal-quotient
,quotient-precision ,precision-data ,scale-data
Arguments:
packed-decimal-dividend
VMS usage: varying_arg
type: packed decimal string
access: read only
mechanism: by reference
Dividend. The packed-decimal-dividend argument is the address of a
packed decimal string which contains the shifted dividend.
packed-decimal-divisor
VMS usage: varying_arg
type: packed decimal string
access: read only
mechanism: by reference
Divisor. The packed-decimal-divisor argument is the address of a
packed decimal string which contains the divisor.
divisor-precision
VMS usage: word_signed
type: word integer (signed)
access: read only
mechanism: by value
Precision of the divisor. The divisor-precision argument is a
signed word integer which contains the precision of the divisor.
The high order bits are filled with zeros.
packed-decimal-quotient
VMS usage: varying_arg
type: packed decimal string
access: write only
mechanism: by reference
Quotient. The packed-decimal-quotient argument is the address of
the packed decimal string into which OTS$DIV_PK_LONG writes the
quotient.
quotient-precision
VMS usage: word_signed
type: word integer (signed)
access: read only
mechanism: by value
Precision of the quotient. The quotient-precision argument is a
signed word integer that contains the precision of the quotient.
The high order bits are filled with zeros.
precision-data
VMS usage: word_signed
type: word integer (signed)
access: read only
mechanism: by value
Additional digits of precision required. The precision-data
argument is a signed word integer that contains the value of the
additional digits of precision required.
scale-data
VMS usage: word_signed
type: word integer (signed)
access: read only
mechanism: by value
The scale-data argument is a signed word integer that contains the
scale data.
OTS$DIV_PK_SHORT
The Packed Decimal Division with Short Divisor routine divides
fixed-point decimal data, which is stored in packed decimal form,
when precision and scale requirements for the quotient call for
multiple-precision division. The divisor can have a maximum
precision of twenty-nine digits.
Format:
OTS$DIV_PK_SHORT packed-decimal-dividend ,packed-decimal-divisor
,divisor-precision ,packed-decimal-quotient
,quotient-precision ,precision-data
Arguments:
packed-decimal-dividend
VMS usage: varying_arg
type: packed decimal string
access: read only
mechanism: by reference
Dividend.The packed-decimal-dividend argument is the address of a
packed decimal string which contains the shifted dividend.
packed-decimal-divisor
VMS usage: varying_arg
type: packed decimal string
access: read only
mechanism: by reference
Divisor. The packed-decimal-divisor argument is the address of a
packed decimal string which contains the divisor.
divisor-precision
VMS usage: word_signed
type: word integer (signed)
access: read only
mechanism: by value
Precision of the divisor. The divisor-precision argument is a
signed word integer which contains the precision of the divisor.
The high-order bits are filled with zeros.
packed-decimal-quotient
VMS usage: varying_arg
type: packed decimal string
access: write only
mechanism: by reference
Quotient. The packed-decimal-quotient argument is the address of a
packed decimal string into which OTS$DIV_PK_SHORT writes the
quotient.
quotient-precision
VMS usage: word_signed
type: word integer (signed)
access: read only
mechanism: by value
Precision of the quotient. The quotient-precision argument is a
signed word integer which contains the precision of the quotient.
The high-order bits are filled with zeros.
precision-data
VMS usage: word_signed
type: word integer (signed)
access: read only
mechanism: by value
Additional digits of precision required. The precision-data
argument is a signed word integer which contains the value of the
additional digits of precision required.
OTS$MOVE3
The Move Data Without Fill routine moves up to 2**31-1bytes,
(2,147,483,647 bytes) from a specified source address to a specified
destination address.
Format:
OTS$MOVE3 length-value ,source-array ,destination-array
Arguments:
length-value
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by value
Number of bytes of data to move. The length-value argument contains
the number of bytes to move. The value of length-value may range
from 0 to 2,147,483,647 bytes.
source-array
VMS usage: vector_byte_unsigned
type: byte (unsigned)
access: read only
mechanism: by reference, array reference
Data to be moved by OTS$MOVE3. The source-array argument contains
the address of an unsigned byte array that contains this data.
destination-array
VMS usage: vector_byte_unsigned
type: byte (unsigned)
access: write only
mechanism: by reference, array reference
Item into which source-array will be moved. The destination-array
argument is the address of an unsigned byte array into which
OTS$MOVE3 writes the source data.
OTS$MOVE5
The Move Data with Fill routine moves up to 2**31-1bytes,
(2,147,483,647 bytes) from a specified source address to a specified
destination address, with separate source and destination lengths,
and with fill. Overlap of the source and destination arrays does
not affect the result.
Format:
OTS$MOVE5 longword-int-source-length ,source-array ,fill-value
,longword-int-dest-length ,destination-array
Arguments:
longword-int-source-length
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by value
Number of bytes of data to move. The longword-int-source-length
argument contains a signed longword integer that is this number.
The value of longword-int-source-length may range from 0 to
2,147,483,647.
source-array
VMS usage: vector_byte_unsigned
type: byte (unsigned)
access: read only
mechanism: by reference, array reference
Data to be moved by OTS$MOVE5. The source-array argument contains
the address of an unsigned byte array that contains this data.
fill-value
VMS usage: byte_unsigned
type: byte (unsigned)
access: read only
mechanism: by value
Character used to pad the source data if longword-int-source-length
is less than longword-int-dest-length. The fill-value argument
contains the address of an unsigned byte that is this character.
longword-int-dest-length
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by value
Size of the destination area in bytes. The longword-int-dest-length
argument is a signed longword integer containing this size. The
value of longword-int-dest-length may range from 0 through
2,147,483,647.
destination-array
VMS usage: vector_byte_unsigned
type: byte (unsigned)
access: write only
mechanism: by reference, array reference
Item into which source-array will be moved. The destination-array
argument is the address of an unsigned byte array into which
OTS$MOVE5 will write the source data.
OTS$MULCx
The Complex Multiplication routines calculate the complex product of
two complex values.
Format:
OTS$MULCD_R3 complex-multiplier ,complex-multiplicand
OTS$MULCG_R3 complex-multiplier ,complex-multiplicand
The above formats correspond to the D_floating and
G_floating complex types.
Arguments:
complex-multiplier
VMS usage: complex_number
type: D_floating complex, G_floating complex
access: read only
mechanism: by value
Complex multiplier. The complex-multiplier argument contains the
multiplier. For OTS$MULCD_R3, complex-multiplier is a D_floating
complex number. For OTS$MULCG_R3, complex-multiplier is a
G_floating complex number.
complex-multiplicand
VMS usage: complex_number
type: D_floating complex, G_floating complex
access: read only
mechanism: by value
Complex multiplicand. The complex-multiplicand argument contains
the multiplicand. For OTS$MULCD_R3, complex-multiplicand is a
D_floating complex number. For OTS$MULCG_R3, complex-multiplicand
is an F_floating complex number.
OTS$POWCxCx
The Raise a Complex Base to a Complex Floating-Point Exponent
routines return the result of raising a complex base to a complex
exponent.
Format:
OTS$POWCC complex-base ,complex-exponent-value
OTS$POWCDCD_R3 complex-base ,complex-exponent-value
OTS$POWCGCG_R3 complex-base ,complex-exponent-value
Each of the above three formats corresponds to one
of the three floating-point complex types.
Arguments:
complex-base
VMS usage: complex_number
type: F_floating complex, D_floating complex, G_floating complex
access: read only
mechanism: by value
Complex base. The complex-base argument contains the value of the
base. For OTS$POWCC, complex-base is an F_floating complex number.
For OTS$POWCDCD_R3, complex-base is a D_floating complex number.
For OTS$POWCGCG_R3, complex-base is a G_floating complex number.
complex-exponent-value
VMS usage: complex_number
type: F_floating complex, D_floating complex, G_floating complex
access: read only
mechanism: by value
Complex exponent. The complex-exponent-value argument contains the
value of the exponent. For OTS$POWCC, complex-exponent-value is an
F_floating complex number. For OTS$POWCDCD_R3,
complex-exponent-value is a D_floating complex number. For
OTS$POWCGCG_R3, complex-exponent-value is a G_floating complex
number.
OTS$POWCxJ
The Raise a Complex Base to a Signed Longword Integer Exponent
routines return the complex result of raising a complex base to an
integer exponent.
Format:
OTS$POWCJ complex-base ,longword-integer-exponent
OTS$POWCDJ_R3 complex-base ,longword-integer-exponent
OTS$POWCGJ_R3 complex-base ,longword-integer-exponent
Each of the above three formats corresponds to one
of the three floating-point complex types.
Arguments:
complex-base
VMS usage: complex_number
type: F_floating complex, D_floating complex, G_floating complex
access: read only
mechanism: by value
Complex base. The complex-base argument contains the complex base.
For OTS$POWCJ, complex-base is an F_floating complex number. For
OTS$POWCDJ_R3, complex-base is a D_floating complex number. For
OTS$POWCGJ_R3, complex-base is a G_floating complex number.
longword-integer-exponent
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by value
Exponent. The longword-integer-exponent argument is a signed
longword integer containing the exponent.
OTS$POWDD
The Exponentiation of a D_floating Base to a D_floating Exponent
routine raises a D_floating base to a D_floating exponent.
Format:
OTS$POWDD D-floating-point-base ,D-floating-point-exponent
The above format corresponds to raising the
D_floating base to a D_floating exponent.
Arguments:
D-floating-point-base
VMS usage: floating_point
type: D_floating
access: read only
mechanism: by value
Base. The D-floating-point-base argument is a D_floating number
containing the base.
D-floating-point-exponent
VMS usage: floating_point
type: D_floating
access: read only
mechanism: by value
Exponent. The D-floating-point-exponent argument contains the
exponent. The D-floating-point-exponent is a D_floating number.
OTS$POWDJ
The Exonentiation of a D_floating Base routine raises a D_floating
base to a longword exponent.
Format:
OTS$POWDJ D-floating-point-base ,longword-integer-exponent
Arguments:
D-floating-point-base
VMS usage: floating_point
type: D_floating
access: read only
mechanism: by value
Base. The D-floating-point-base argument is a D_floating number
containing the base.
longword-integer-exponent
VMS usage: longword_signed
type: longword (signed)
access: read only
mechanism: by value
Exponent. The longword-integer-exponent argument contains the
signed longword integer exponent.
OTS$POWDR
The Exponentiation of a D_floating Base to an F_floating Exponent
routines raise a D_floating base to an F_floating exponent.
Format:
OTS$POWDR D-floating-point-base ,F-floating-point-exponent
The above format correspond to raising the
D_floating base to an F_floating exponent.
Arguments:
D-floating-point-base
VMS usage: floating_point
type: D_floating
access: read only
mechanism: by value
Base. The D-floating-point-base argument is a D_floating number
containing the base.
F-floating-point-exponent
VMS usage: floating_point
type: F_floating
access: read only
mechanism: by value
Exponent. The F-floating-point-exponent argument contains the
exponent. The F-floating-point-exponent is an F_floating number.
OTS$POWGG
The Raise a G_floating Base to a G_floating Exponent routine raises
a G_floating base to a G_floating exponent.
Format:
OTS$POWGG G-floating-point-base ,G-floating-point-exponent
Arguments:
G-floating-point-base
VMS usage: floating_point
type: G_floating
access: read only
mechanism: by value
Base which OTS$POWGx raises to a G_floating or longword exponent.
The G-floating-point-base argument is a G_floating number containing
the base.
G-floating-point-exponent
VMS usage: floating_point
type: G_floating
access: read only
mechanism: by value
Exponent to which OTS$POWGG raises the base. The
G-floating-point-exponent argument is a G_floating number containing
the exponent.
OTS$POWGJ
The Raise a G_floating Base to a Longword Exponent routine raises a
G_floating base to a longword exponent.
Format:
OTS$POWGJ G-floating-point-base ,longword-integer-exponent
Arguments:
G-floating-point-base
VMS usage: floating_point
type: G_floating
access: read only
mechanism: by value
Base which OTS$POWGJ raises to a longword exponent. The
G-floating-point-base argument is a G_floating number containing the
base.
longword-integer-exponent
VMS usage: longword_signed
type: longword (signed)
access: read only
mechanism: by value
Exponent to which OTS$POWGJ raises the base. The
longword-integer-exponent argument is a signed longword integer
containing the exponent.
OTS$POWHH_R3
The Exponentiation of an H_floating Base to an H_floating Exponent
routine raises an H_floating base to an H_floating exponent.
Format:
OTS$POWHH_R3 H-floating-point-base ,H-floating-point-exponent
Arguments:
H-floating-point-base
VMS usage: floating_point
type: H_floating
access: read only
mechanism: by value
Base. The H-floating-point-base argument is an H_floating number
containing the base.
H-floating-point-exponent
VMS usage: floating_point
type: H_floating
access: read only
mechanism: by value
Exponent. The H-floating-point-exponent argument contains the
H-floating exponent.
OTS$POWHJ_R3
The Exponentiation of an H_floating Base to a Longword Exponent
routine raises an H_floating base to a longword exponent.
Format:
OTS$POWHJ_R3 H-floating-point-base ,longword-integer-exponent
Arguments:
H-floating-point-base
VMS usage: floating_point
type: H_floating
access: read only
mechanism: by value
Base. The H-floating-point-base argument is an H_floating number
containing the base.
longword-integer-exponent
VMS usage: longword_signed
type: longword (signed)
access: read only
mechanism: by value
Exponent. The longword-integer-exponent argument contains the
signed longword exponent.
OTS$POWII
The Exponentiation of a Word Base to a Word Exponent routine raises
a word base to a word exponent.
Format:
OTS$POWII word-integer-base ,word-integer-exponent
Arguments:
word-integer-base
VMS usage: word_signed
type: word integer (signed)
access: read only
mechanism: by value
Base. The word-integer-base argument is a signed word integer
containing the base.
word-integer-exponent
VMS usage: word_signed
type: word integer (signed)
access: read only
mechanism: by value
Exponent. The word-integer-exponent argument is a signed word
integer containing the exponent.
OTS$POWJJ
The Raise a Longword Base to a Longword Exponent routine raises a
signed longword base to a signed longword exponent.
Format:
OTS$POWJJ longword-integer-base ,longword-integer-exponent
Arguments:
longword-integer-base
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by value
Base. The longword-integer-base argument is a signed longword
integer containing the base.
longword-integer-exponent
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by value
Exponent. The longword-integer-exponent argument is a signed
longword integer containing the exponent.
OTS$POWLULU
The Raise an Unsigned Longword Integer Base to an Unsigned Longword
Exponent routine returns the result of raising an unsigned longword
integer base to an unsigned longword integer exponent.
Format:
OTS$POWLULU
unsigned-lword-int-base, unsigned-lword-int-exponent
Arguments:
unsigned-lword-int-base
VMS usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by value
Unsigned longword integer base. The unsigned-lword-int-base
argument contains the value of the integer base.
unsigned-lword-int-exponent
VMS usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by value
Unsigned longword integer exponent. The unsigned-lword-int-exponent
argument contains the value of the integer exponent.
OTS$POWxLU
The Raise a Floating-Point Base to an Unsigned Longword Integer
Exponent routines return the result of raising a floating-point base
to an unsigned longword integer exponent.
Format:
OTS$POWRLU
floating-point-base ,unsigned-lword-int-exponent
OTS$POWDLU
floating-point-base ,unsigned-lword-int-exponent
OTS$POWGLU
floating-point-base ,unsigned-lword-int-exponent
OTS$POWHLU_R3
floating-point-base ,unsigned-lword-int-exponent
Arguments:
floating-point-base
VMS usage: floating_point
type: F_floating, D_floating, G_floating, H_floating
access: read only
mechanism: by value
Floating-point base. The floating-point-base argument contains the
value of the base. For OTS$POWRLU, floating-point-base is an
F_floating number. For OTS$POWDLU, floating-point-base is a
D_floating number. For OTS$POWGLU, floating-point-base is a
G_floating number. For OTS$POWHLU_R3, floating-point-base is an
H_floating number.
unsigned-lword-int-exponent
VMS usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by value
Integer exponent. The unsigned-lword-int-exponent argument contains
the value of the unsigned longword integer exponent.
OTS$POWRD
The Exponentiation of an F_floating Base to a D_floating Exponent
routine raises an F_floating base to a D_floating exponent.
Format:
OTS$POWRD F-floating-point-base ,D-floating-point-exponent
The above format corresponds to raising the base to
a D_floating exponent.
Arguments:
F-floating-point-base
VMS usage: floating_point
type: F_floating
access: read only
mechanism: by value
Base. The F-floating-point-base argument is an F_floating number
containing the base.
D-floating-point-exponent
VMS usage: floating_point
type: D_floating
access: read only
mechanism: by value
Exponent. The D-floating-point-exponent argument contains the
exponent. The D-floating-point-exponent is a D-floating number.
OTS$POWRJ
The Exponentiation of an F_floating Base to a Longword Exponent
routine raises an F_floating base to a longword exponent.
Format:
OTS$POWRJ F-floating-point-base ,longword-integer-exponent
Arguments:
F-floating-point-base
VMS usage: floating_point
type: F_floating
access: read only
mechanism: by value
Base. The F-floating-point-base argument is an F_floating number
containing the base.
longword-integer-exponent
VMS usage: longword_signed
type: longword (signed)
access: read only
mechanism: by value
Exponent. The longword-integer-exponent argument contains the
longword integer exponent.
OTS$POWRR
The Exponentiation of an F_floating Base to an F_floating Exponent
routine raises an F_floating base to an F_floating exponent.
Format:
OTS$POWRR F-floating-point-base ,F-floating-point-exponent
The above format corresponds to raising the base to
an F_floating exponent.
Arguments:
F-floating-point-base
VMS usage: floating_point
type: F_floating
access: read only
mechanism: by value
Base. The F-floating-point-base argument is an F_floating number
containing the base.
F-floating-point-exponent
VMS usage: floating_point
type: F_floating
access: read only
mechanism: by value
Exponent. The F-floating-point-exponent argument contains the
exponent. The F-floating-point-exponent is an F_floating number.
OTS$SCOPY_DXDX
The Copy a Source String Passed by Descriptor to a Destination
String routine copies a source string to a destination string. Both
strings are passed by descriptor.
Format:
OTS$SCOPY_DXDX source-string ,destination-string
Arguments:
source-string
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
Source string. The source-string argument is the address of a
descriptor pointing to the source string. The descriptor class can
be unspecified, fixed length, dynamic, scalar decimal, array,
noncontiguous array, or varying.
destination-string
VMS usage: char_string
type: character string
access: write only
mechanism: by descriptor
Destination string. The destination-string argument is the address
of a descriptor pointing to the destination string. The class field
determines the appropriate action.
OTS$SCOPY_R_DX
The Copy a Source String Passed By Reference to a Destination String
routine copies a source string passed by reference to a destination
string.
Format:
OTS$SCOPY_R_DX word-int-source-length-val
,source-string-address ,destination-string
Arguments:
word-int-source-length-val
VMS usage: word_unsigned
type: word (unsigned)
access: read only
mechanism: by value
Length of the source string. The word-int-source-length-val
argument is an unsigned word integer containing the length of the
source string.
source-string-address
VMS usage: char_string
type: character string
access: read only
mechanism: by reference
Source string. The source-string-address argument is the address of
the source string.
destination-string
VMS usage: char_string
type: character string
access: write only
mechanism: by descriptor
Destination string. The destination-string argument is the address
of a descriptor pointing to the destination string. The class field
determines the appropriate action. The length field (DSC$W_LENGTH)
alone or both the address (DSC$A_POINTER) and length fields can be
modified if the string is dynamic. For varying strings, the current
length is rewritten.
OTS$SFREE1_DD
The Free One Dynamic String routine returns one dynamic string area
to free storage.
Format:
OTS$SFREE1_DD dynamic-descriptor
Arguments:
dynamic-descriptor
VMS usage: quadword_unsigned
type: quadword (unsigned)
access: modify
mechanism: by reference
Dynamic string descriptor. The dynamic-descriptor argument is the
address of the dynamic string descriptor. The descriptor is assumed
to be dynamic and its class field is not checked.
OTS$SFREEN_DD
The Free N Dynamic Strings routine takes as input a vector of one or
more dynamic string areas and returns them to free storage.
Format:
OTS$SFREEN_DD descriptor-count-value ,first-descriptor
Arguments:
descriptor-count-value
VMS usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by value
Number of adjacent descriptors to be flagged as having no allocated
area (DSC$A_POINTER = 0 and DSC$W_LENGTH = 0) and to have their
allocated areas returned to free storage by OTS$SFREEN_DD. The
descriptor-count-value argument is an unsigned longword containing
this number.
first-descriptor
VMS usage: quadword_unsigned
type: quadword (unsigned)
access: modify
mechanism: by reference
First string descriptor of an array of string descriptors. The
first-descriptor argument is the address of the first string
descriptor. The descriptors are assumed to be dynamic, and their
class fields are not checked.
OTS$SGET1_DD
The Get One Dynamic String routine allocates a specified number of
bytes of dynamic virtual memory to a specified string descriptor.
Format:
OTS$SGET1_DD word-integer-length-value ,dynamic-descriptor
Arguments:
word-integer-length-value
VMS usage: word_unsigned
type: word (unsigned)
access: read only
mechanism: by value
Number of bytes to be allocated. The word-integer-length-value
argument contains the number of bytes. The amount of storage
allocated is automatically rounded up. If the number of bytes is
zero, a small number of bytes is allocated.
dynamic-descriptor
VMS usage: quadword_unsigned
type: quadword (unsigned)
access: modify
mechanism: by reference
Dynamic string descriptor to which the area is to be allocated. The
dyn-str argument is the address of the dynamic string descriptor.
The class field is not checked but it is set to dynamic (DSC$B_CLASS
= 2). The length field (DSC$W_LENGTH) is set to
word-integer-length-value and the address field (DSC$A_POINTER) is
set to the string area allocated (first byte beyond the header).
PPL$
Additional information available:
PPL$ADJUST_QUORUMPPL$ADJUST_SEMAPHORE_MAXIMUM
PPL$AWAIT_EVENTPPL$CREATE_APPLICATIONPPL$CREATE_BARRIER
PPL$CREATE_EVENTPPL$CREATE_SEMAPHOREPPL$CREATE_SHARED_MEMORY
PPL$CREATE_SPIN_LOCKPPL$CREATE_WORK_QUEUEPPL$CREATE_VM_ZONE
PPL$DECREMENT_SEMAPHOREPPL$DELETE_APPLICATIONPPL$DELETE_BARRIER
PPL$DELETE_EVENTPPL$DELETE_SEMAPHOREPPL$DELETE_SHARED_MEMORY
PPL$DELETE_SPIN_LOCKPPL$DELETE_VM_ZONEPPL$DELETE_WORK_ITEM
PPL$DELETE_WORK_QUEUEPPL$DISABLE_EVENTPPL$ENABLE_EVENT_AST
PPL$ENABLE_EVENT_SIGNALPPL$FIND_OBJECT_IDPPL$FIND_SYNCH_ELEMENT_ID
PPL$FLUSH_SHARED_MEMORYPPL$GET_INDEXPPL$INCREMENT_SEMAPHORE
PPL$INDEX_TO_PIDPPL$INITIALIZEPPL$INSERT_WORK_ITEM
PPL$PID_TO_INDEXPPL$READ_BARRIERPPL$READ_EVENTPPL$READ_SEMAPHORE
PPL$READ_SPIN_LOCKPPL$READ_WORK_QUEUEPPL$RELEASE_SPIN_LOCK
PPL$REMOVE_WORK_ITEMPPL$RESET_EVENTPPL$SEIZE_SPIN_LOCK
PPL$SET_SEMAPHORE_MAXIMUMPPL$SET_QUORUMPPL$SPAWN
PPL$STOPPPL$TERMINATEPPL$TRIGGER_EVENTPPL$UNIQUE_NAME
PPL$WAIT_AT_BARRIER
PPL$ADJUST_QUORUM
The Adjust Barrier Quorum routine increments or decrements the
quorum associated with the specified barrier, thus allowing a
barrier to dynamically alter the number of participants required to
conclude a wait on that barrier.
Format:
PPL$ADJUST_QORUM barrier-id ,amount
Arguments:
barrier-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Identifier of the barrier. The barrier-id argument is the address of
an unsigned longword containing the identifer.
amount
VMS usage: word_signed
type: word (signed)
access: read only
mechanism: by reference
Value to be added to the barrier quorum. The amount argument is the
address of a signed word integer containing this value. A negative
value may be specified to decrement the quorum.
PPL$ADJUST_SEMAPHORE_MAXIMUM
The Adjust a Semaphore Maximum routine increments or decrements
the maximum associated with a semaphore.
Format
PPL$ADJUST_SEMAPHORE_MAXIMUM semaphore-id, amount
Arguments
semaphore-id
VMS Usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Identifier of the semaphore. The semaphore-id argument is the
address of an unsigned longword containing the identifier.
amount
VMS Usage: word_signed
type: word (signed)
access: read only
mechanism: by reference
Value to add to the semaphore maximum. The amount argument is the
address of a signed word containing the amount. Specify a positive
value for amount to increase the maximum; specify a negative value
to decrease the maximum.
PPL$AWAIT_EVENT
The Await Event Occurrence routine blocks the caller until an
event occurs.
Format
PPL$AWAIT_EVENT event-id [,output]
Arguments
event-id
VMS Usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Identifier of the event. The event-id argument is the address of
an unsigned longword containing the identifier.
The event-id is returned by PPL$CREATE_EVENT.
output
VMS Usage: user_arg
type: longword (unsigned)
access: write only
mechanism: by reference
Receives the event-param argument from PPL$TRIGGER_EVENT. The
output argument is the address of an unsigned longword that
receives the value of event-param. The value of event-param is
copied to output when an event is triggered.
PPL$CREATE_APPLICATION
The Form or Join a PPL$ Application routine informs the PPL$
facility that the calling process is forming or joining a parallel
application.
Format
PPL$CREATE_APPLICATION [size] [,application-name]
[,protection] [,flags]
Arguments
size
VMS Usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
Number of pages that PPL$ allocates for its internal data
structures. The optional size argument is the address of an
unsigned longword containing this size value. See the Description
section for information about the default value.
application-name
VMS Usage: char_string
type: character string
access: read only
mechanism: by descriptor
The name of the application that the calling process will form or
join. The optional application-name argument is the address of a
descriptor pointing to a character string containing the name of
the application. The application-name argument can contain up to
11 characters.
protection
VMS Usage: file_protection
type: longword (unsigned)
access: read only
mechanism: by reference
Numeric value representing the protection mask to be applied to
the application. The optional protection argument is the address
of an unsigned longword containing this numeric value. For more
information, see the description of the $CRMPSC system service in
the VMS System Services Reference Manual.
flags
VMS Usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies options for forming or joining a PPL$ application. The
flags argument is a longword bit mask containing the flags.
PPL$CREATE_BARRIER
The Create Barrier routine creates and initializes a barrier, and
returns the barrier identifer. You use the barrier identifier to
cal PPL$WAIT_AT_BARRIER.
Format:
PPL$CREATE_BARRIER barrier-id [,barrier-name] [,quorum]
Arguments:
barrier-id
VMS usage: identifier
type: longword (unsigned)
access: write only
mechanism: by reference
Identifier of the barrier. The barrier-id argument is the address of
an unsigned longword containing the identifer. Barrier-id must be
used in other calls to identify the barrier.
barrier-name
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
Name of the barrier. The optional barrier-name argument is the
address of a descriptor pointing to the barrier name. The name of
the barrier is entirely arbitrary.
quorum
VMS usage: word_signed
type: word (signed)
access: read only
mechanism: by reference
The number of participants that are required to terminate an active
wait for this barrier. For example, a quorum of 3 indicates that the
first two callers of PPL$WAIT_AT_BARRIER who specify this barrier-id
will be blocked until a third caller issues that request. At that
point, all three will be released for further processing. If this
parameter is not specified, a default value of 1 is assigned for the
quorum.
PPL$CREATE_EVENT
The Create Event routine creates an arbitrary user-defined event and
returns its identifier, which is used in subsequent calls to other
PPL$ event services.
Format:
PPL$CREATE_EVENT event-id [,event-name]
Arguments:
event-id
VMS usage: identifier
type: longword (unsigned)
access: write only
mechanism: by reference
Identifier of the event. The event-id argument is the address of an
unsigned longword containing the identifier. The event-id must be
used in other calls to identify the event.
event-name
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
Name of the event. The event-name argument is the address of a
descriptor for the event name. The name of the event is entirely
arbitrary. If you do not specify a value for event-name, or if you
specify zero, a new anonymous (unnamed) event is created, which may
only be referenced by its identifier. An arbitrary number of
anonymous events may be created by a given application.
PPL$CREATE_SEMAPHORE
The Create Semaphore routine creates and initializes a semaphore
with a waiting queue, and returns the semaphore identifier. You use
the semaphore identifer to perform all operations on that semaphore.
Format:
PPL$CREATE_SEMAPHORE semaphore-id [,semaphore-name]
[,semaphore-maximum] [,semaphore-initial]
Arguments:
semaphore_id
VMS usage: identifier
type: longword (unsigned)
access: write only
mechanism: by reference
Identifier of the semaphore. The semaphore-id argument is the
address of an unsigned longword containing the identifier.
Semaphore-id must be used in other calls to identify the semaphore.
semaphore-name
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
Name of the semaphore. The semaphore-name argument is the address of
a descriptor pointing to the semaphore name. The name of the
semaphore is entirely arbitrary. If you do not specify a value for
semaphore-name, or if you specify zero, a new anonymous (unnamed)
semaphore is created. An arbitrary number of anonymous semaphores
may be created by a given application.
semaphore-maximum
VMS usage: word_signed
type: word (signed)
access: read only
mechanism: by reference
Maximum value of the semaphore. The semaphore-maximum argument is
the address of a signed word containing the maximum value. This
value must be non-negative. If you do not supply a value for
semaphore-maximum, a default value of one is used, thereby making
it a binary semaphore.
semaphore-initial
VMS usage: word_signed
type: word (signed)
access: read only
mechanism: by reference
Initial value of the semaphore. The semaphore-initial argument is
the address of a signed word containing the initial value. This
value must be less than or equal to the semaphore-maximum value. If
you do not supply a value for semaphore-initial, a default value
equal to semaphore-maximum is used.
PPL$CREATE_SHARED_MEMORY
The Create Shared Memory routine creates (if necessary) and maps a
section of memory that can be shared by multiple processes.
Format
PPL$CREATE_SHARED_MEMORY section-name ,memory-area [,flags]
[,file-name] [,protection]
Arguments
section-name
VMS Usage: char_string
type: character string
access: read only
mechanism: by descriptor
Name of the shared memory section you want to create. The section-
name argument is the address of a descriptor pointing to the
shared memory section name.
memory-area
VMS Usage: vector_longword_unsigned
type: longword (unsigned)
access: modify
mechanism: by reference, array reference
The area of memory into which the shared memory is mapped. The
memory-area argument is the address of a two-longword array
containing, in order, the length (in bytes) and the starting
virtual address for the area of memory.
If you specify the starting address as zero, the PPL$ facility
selects the virtual address space so that each current process
in the application can map the section to the same set of virtual
addresses.
PPL$CREATE_SHARED_MEMORY returns to this argument the actual
length and starting virtual address of the shared memory created
or mapped.
flags
VMS Usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies options for creating and mapping shared memory. The
flags argument is the address of a longword bit mask containing
the flag.
file-name
VMS Usage: char_string
type: character string
access: read only
mechanism: by descriptor
Name of the file used for backup storage of the shared memory. The
file-name argument is the address of a descriptor pointing to the
file name. The size of the resulting address space is the smaller
of the following:
the specified section size
the size of the file being mapped
If you do not specify a file name, PPL$CREATE_SHARED_MEMORY
creates for backup storage a page file section instead of a disk
file section.
If you specify a file that does not exist, PPL$CREATE_SHARED_
MEMORY creates it.
protection
VMS Usage: file_protection
type: longword (unsigned)
access: read only
mechanism: by reference
Numeric value representing the protection mask to be applied
to the shared memory. The optional protection argument is the
address of an unsigned longword containing this numeric value.
If you do not specify a value, the default is the value for
protection specified in the call to PPL$CREATE_APPLICATION.
For more information, see the description of the $CRMPSC system
service in the VMS System Services Reference Manual.
PPL$CREATE_SPIN_LOCK
The Create Spin Lock routine creates and initializes a simple (spin)
lock, and returns the identifier that you use to get and free the
lock.
Format:
PPL$CREATE_SPIN_LOCK lock-id [,lock-name]
Arguments:
lock-id
VMS usage: identifier
type: longword (unsigned)
access: write only
mechanism: by reference
Identifier of the newly created lock. The lock-id argument is the
address of an unsigned longword containing the lock identifier. You
must use lock-id when getting or freeing the lock.
lock-name
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
Name of the lock. The lock-name argument is the address of a
descriptor pointing to the name. The name of the lock is entirely
arbitrary. If you do not specify this argument, or if you specify
zero, an anonymous (unnamed) lock is created. An arbitrary number of
anonymous locks may be created by a given application.
PPL$CREATE_WORK_QUEUE
The Create a Work Queue routine creates and initializes a work
queue, and returns the work queue identifier.
Format
PPL$CREATE_WORK_QUEUE queue-id [,queue-name]
Arguments
queue-id
VMS Usage: identifier
type: longword (unsigned)
access: write only
mechanism: by reference
The work queue identifier. The queue-id argument is the address
of an unsigned longword containing the identifier. Queue-id must
be used in calls to the other work queue routines to identify the
work queue.
queue-name
VMS Usage: char_string
type: character string
access: read only
mechanism: by descriptor
Name of the work queue. The optional queue-name argument is the
address of a descriptor pointing to a character string containing
the work queue name. The work queue name is case sensitive. If you
do not specify this argument, or if you specify 0, an unnamed work
queue is created. An arbitrary number of unnamed work queues may
be created by a given application.
PPL$CREATE_VM_ZONE
The Create a New Zone routine creates a new storage zone according
to specified arguments.
Format:
PPL$CREATE_VM_ZONE zone-id [,algorithm] [,algorithm-argument]
[,flags] [,extend-size] [,initial-size] [,block-size]
[,alignment] [,page-limit] [,smallest-block-size]
[,zone-name]
Arguments:
zone-id
VMS usage: identifier
type: longword (unsigned)
access: write only
mechanism: by reference
Zone identifier. The zone-id argument is the address of a longword
that is set to the zone identifier of the newly created zone.
algorithm
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Algorithm. The algorithm argument is the address of a longword
integer that represents the code for one of the LIB$VM algorithms:
1 LIB$K_VM_FIRST_FIT First fit
2 LIB$K_VM_QUICK_FIT Quick fit, lookaside list
3 LIB$K_VM_FREQ_SIZES Frequent sizes, lookaside
list
4 LIB$K_VM_FIXED Fixed size blocks
algorithm-argument
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Algorithm argument. The algorithm-argument argument is the address
of a signed longword that contains a value that is specific to the
particular allocation algorithm.
Algorithm Value
QUICK_FIT The number of queues used. The number of
queues must be between 1 and 128.
FREQ_SIZES The number of cache slots used. The number
of cache slots must be between 1 and 16.
FIXED The fixed request size (in bytes) for each
get or free. The request size must be
greater than 0.
FIRST_FIT Not used, may be omitted.
flags
VMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Flags. The flags argument is the address of an unsigned longword
that contains flag bits that control various options:
Bit Value Description
Bit 0 LIB$M_VM_BOUNDARY_TAGS Boundary tags for faster freeing
Adds a minimum of eight bytes to
each block
Bit 1 LIB$M_VM_GET_FILL0 LIB$GET_VM; fill with bytes of 0
Bit 2 LIB$M_VM_GET_FILL1 LIB$GET_VM; fill with bytes of
FF (hexadecimal)
Bit 3 LIB$M_VM_FREE_FILL0 LIB$FREE_VM; fill with bytes of
0
Bit 4 LIB$M_VM_FREE_FILL1 LIB$FREE_VM; fill with bytes of
FF (hexadecimal)
Bit 5 LIB$M_VM_EXTEND_AREA Add extents to existing areas if
possible
extend-size
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Zone extend size. The extend-size argument is the address of signed
longword that contains the number of (512-byte) pages to be added to
the zone each time it is extended.
initial-size
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Initial size for the zone. The initial-size argument is the address
of a signed longword that contains the number of (512-byte) pages
to be allocated for the zone as the zone is created.
block-size
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Block size of the zone. The block-size argument is the address of a
signed longword specifying the allocation quantum (in bytes) for
the zone. All blocks allocated are rounded up to a multiple of
block-size.
alignment
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Block alignment. The alignment argument is the address of a
signed longword that specifies the required address alignment (in
bytes) for each block allocated.
page-limit
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Maximum page limit. The page-limit argument is the address of a
signed longword that specifies the maximum number of (512-byte)
pages that can be allocated for the zone. The value of page-limit
must be between 0 and 32,767. Note that part of the zone is used
for header information.
smallest-block-size
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Smallest block size. The smallest-block-size argument is the
address of a signed longword that specifies the smallest block
size (in bytes) that has a queue for the quick fit algorithm.
zone-name
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
Name to be associated with the zone being created. The optional
zone-name argument is the address of a descriptor pointing to the
zone name. If zone-name is not specified, the zone will not have an
associated name.
PPL$DECREMENT_SEMAPHORE
The Decrement a Semaphore routine waits for a semaphore to have a
value greater than zero, then decrements the value by one to
indicate the allocation of a resource. If the value of the
semaphore is zero, the process is put in the waiting queue and the
execution path is suspended.
Format:
PPL$DECREMENT_SEMAPHORE semaphore-id [,flags] [,spin]
Arguments:
semaphore-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Identifier of the semaphore. The semaphore-id argument is the
address of an unsigned longword containing the identifier.
flags
VMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies options for the decrement semaphore operation. The flags
argument is a longword bit mask containing the flag. Valid values
are as follows:
PPL$M_NON_BLOCKING Indicates that the caller is not
to block if the resource is not
available. The default is FALSE:
the caller will block if resource
is unavailable.
PPL$M_SPIN_WAIT Indicates that the caller is never
to block, but rather to always spin
while waiting at this barrier.
PPL$M_SPIN_COUNTED Indicates that the caller wishes to
spin for a given amount of
instructions and then to block.
The default is block immediately,
do not spin at all.
spin
VMS usage: mask_longword
type: long (unsigned)
access: read only
mechanism: by reference
This value must be specified when using the PPL$M_SPIN_COUNTED
flag and represents a relative time that a process will spin
before blocking.
PPL$DELETE_APPLICATION
The Delete a PPL$ Application routine marks all shared memory
for deletion and prevents additional processes from joining the
application.
Format
PPL$DELETE_APPLICATION
Arguments
None.
PPL$DELETE_BARRIER
The Delete a Barrier routine deletes a barrier and releases any
storage associated with it.
Format
PPL$DELETE_BARRIER [barrier-id] [,barrier-name]
Arguments
barrier-id
VMS Usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Identifier of the barrier. The optional barrier-id argument is the
address of an unsigned longword containing the barrier identifier.
barrier-name
VMS Usage: char_string
type: character string
access: read only
mechanism: by descriptor
Name of the barrier. The optional barrier-name argument is the
address of a descriptor pointing to a character string containing
the barrier name.
PPL$DELETE_EVENT
The Delete an Event routine deletes an event and releases any
storage associated with it.
Format
PPL$DELETE_EVENT [event-id] [,event-name]
Arguments
event-id
VMS Usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Identifier of the event. The optional event-id argument is the
address of an unsigned longword containing the event identifier.
event-name
VMS Usage: char_string
type: character string
access: read only
mechanism: by descriptor
Name of the event. The optional event-name argument is the address
of a descriptor pointing to a character string containing the
event name.
PPL$DELETE_SEMAPHORE
The Delete a Semaphore routine deletes a semaphore and releases
any storage associated with it.
Format
PPL$DELETE_SEMAPHORE [semaphore-id] [,semaphore-name]
Arguments
semaphore-id
VMS Usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Identifier of the semaphore. The optional semaphore-id argument
is the address of an unsigned longword containing the semaphore
identifier.
semaphore-name
VMS Usage: char_string
type: character string
access: read only
mechanism: by descriptor
Name of the semaphore. The optional semaphore-name argument is the
address of a descriptor pointing to a character string containing
the semaphore-name.
PPL$DELETE_SHARED_MEMORY
The Delete Shared Memory routine deletes a global section that you
created using the PPL$CREATE_SHARED_MEMORY routine. If desired, this
routine writes the contents of the global section to disk before
deleting the section.
Format:
PPL$DELETE_SHARED_MEMORY section-name [,memory-area]
[,flags]
Arguments:
section-name
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
Name of the global section you want to delete. The section-name
argument is the address of a character string pointing to the global
section name. A VMS global section is a section of memory
potentially available to all processes in the system.
memory-area
VMS usage: vector_longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference, array reference
The area of memory into which the global section that you want to
delete is mapped. The memory-area argument is the address of a
two-longword array containing, in order, the length (in bytes) and
the starting virtual address of the area of memory.
flags
VMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies actions to be performed before deleting the global
section. The flags argument is a longword bit mask containing the
flag. Valid values are as follows:
PPL$M_FLUSH Writes the global section to disk before
deletion.
PPL$M_NOUNI Identifies the global section as having
a non-unique name. By default,
PPL$CREATE_SHARED_MEMORY gives the
specified global section a name unique
to the application by using
PPL$UNIQUE_NAME. If you specified this
value to give the global section a
non-unique name when you called
PPL$CREATE_SHARED_MEM, you must also
specify it when you call
PPL$DELETE_SHARED_MEMORY.
PPL$DELETE_SPIN_LOCK
The Delete a Spin Lock routine deletes a spin lock and releases
any storage associated with it.
Format
PPL$DELETE_SPIN_LOCK [lock-id] [,lock-name]
Arguments
lock-id
VMS Usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Identifier of the lock. The optional lock-id argument is the
address of an unsigned longword containing the lock identifier.
lock-name
VMS Usage: char_string
type: character string
access: read only
mechanism: by descriptor
Name of the lock. The optional lock-name argument is the address
of a descriptor pointing to a character string containing the lock
name.
PPL$DELETE_VM_ZONE
The Delete a Virtual Memory Zone routine deletes a storage zone
and returns all pages owned by the zone to the application-wide
page pool.
Format
PPL$DELETE_VM_ZONE [zone-id] [,zone-name]
Arguments
zone-id
VMS Usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Identifier of the zone. The optional zone-id argument is the
address of an unsigned longword containing the zone identifier.
zone-name
VMS Usage: char_string
type: character string
access: read only
mechanism: by descriptor
Name of the zone. The optional zone-name argument is the address
of a descriptor pointing to a character string containing the zone
name.
PPL$DELETE_WORK_ITEM
The Delete a Work Queue Item routine deletes a work item from a
work queue.
Format
PPL$DELETE_WORK_ITEM queue-id, work-item [,flags]
Arguments
queue-id
VMS Usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
The queue identifier. The queue-id argument is the address of an
unsigned longword containing the identifier.
work-item
VMS Usage: user_arg
type: longword (unsigned)
access: read only
mechanism: by value
The value of the item to be deleted from the queue. The work-item
argument is the address of an unsigned longword containing this
value.
flags
VMS Usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies options for deleting items from a work queue. The
optional flags argument is the address of a longword bit mask
containing the flag.
PPL$DELETE_WORK_QUEUE
The Delete a Work Queue routine deletes the specified work queue,
and releases any storage associated with it.
Format
PPL$DELETE_WORK_QUEUE [queue-id] [,queue-name] [,flags]
Arguments
queue-id
VMS Usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
The work queue identifier. The optional queue-id argument is the
address of an unsigned longword containing the identifier.
queue-name
VMS Usage: char_string
type: character string
access: read only
mechanism: by descriptor
Name of the work queue. The optional queue-name argument is the
address of a descriptor pointing to a character string containing
the work queue name.
flags
VMS Usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies options for deleting a work queue. The optional flags
argument is the address of a longword bit mask containing the
flag.
PPL$DISABLE_EVENT
The Disable Asynchronous Notification of an Event routine disables
delivery to a process of notification of an event by either AST or
signal.
Format
PPL$DISABLE_EVENT event-id
Arguments
event-id
VMS Usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Identifier of the event. The event-id argument is the address of
an unsigned longword containing the identifier.
PPL$ENABLE_EVENT_AST
The Enable AST Notification of an Event routine specifies the
address of an AST routine (and optionally an argument to that
routine) to be delivered when an event occurs.
Format:
PPL$ENABLE_EVENT_AST event-id ,AST-address [,AST-argument]
Arguments:
event-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Identifier of the event. The event-id argument is the address of an
unsigned longword containing the identifier.
AST-address
VMS usage: ast_procedure
type: procedure entry mask
access: call without stack unwinding
mechanism: by reference
AST routine address. The AST-address argument is the address of the
procedure entry mask for the user's AST routine. This routine will
be called on the user's behalf when the event state becomes
occurred.
AST-argument
VMS usage: user_arg
type: longword (unsigned)
access: read only
mechanism: by value
Argument to be passed to the AST routine. The AST-argument argument
contains the value of the argument for the AST routine.
PPL$ENABLE_EVENT_SIGNAL
The Enable Signal Notification of an Event routine specifies a
condition-value to be signaled when the event occurs.
Format:
PPL$ENABLE_EVENT_SIGNAL event-id [,signal-value]
Arguments:
event-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Identifier of the event. The event-id argument is the address of an
unsigned longword containing the identifier.
signal-value
VMS usage: user_arg
type: longword (unsigned)
access: read only
mechanism: by value
User-defined value to be signaled when the event occurs. The
signal-value argument contains the value to be signaled when the
specified event occurs.
PPL$FIND_OBJECT_ID
Given the name of a spin lock, semaphore, barrier, event, work
queue, or shared memory zone, the Find Object Identification
routine returns the identifier of the object associated with the
name you specify.
Format
PPL$FIND_OBJECT_ID object-id ,object-name
Arguments
object-id
VMS Usage: identifier
type: longword (unsigned)
access: modify
mechanism: by reference
Object identifier to be returned. The object-id argument is the
address of an unsigned longword that receives the associated
identifier.
object-name
VMS Usage: char_string
type: character string
access: read only
mechanism: by descriptor
Name of the object for which to return the associated identifier.
The object-name argument is the address of a descriptor pointing
to a character string containing the (user-defined) name of the
object.
PPL$FIND_SYNCH_ELEMENT_ID
Given the name of a spin lock, counting semaphore or barrier, the
Find Synchronization Element Identification routine returns the ID
of an element.
Format:
PPL$FIND_SYNCH_ELEMENT_ID element-id ,element-name
Arguments:
element-id
VMS usage: identifier
type: longword (unsigned)
access: modify
mechanism: by reference
Identifier of the element. The element-id argument is the address
of an unsigned longword that receives the associated identifer.
element-name
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
Name of the synchronization element for which to return the
associated ID. The element-name argument is the address of a
descriptor pointing to the (user-defined) name of the
synchronization element.
PPL$FLUSH_SHARED_MEMORY
The Flush Shared Memory routine writes (flushes) to disk the
contents of a global section that you created using the
PPL$CREATE_SHARED_MEMORY routine. Only pages that have been modified
are flushed to disk.
Format:
PPL$FLUSH_SHARED_MEMORY section-name [,memory-area]
[,flags]
Arguments:
section-name
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
Name of the global section whose contents are to be written to disk.
The section-name argument is the address of a descriptor
pointing to the global section name. A VMS global section is a data
structure or shareable image section potentially available to all
processes in the system.
memory-area
VMS usage: vector_longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
The area of memory into which the specified global section is
mapped. The memory-area argument is the address of a two-longword
array containing, in order, the length (in bytes) and the starting
virtual address for the area of memory.
flags
VMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies actions to perform before flushing the global section.
The flags argument is a longword bit mask containing the flag. The
valid value is as follows:
PPL$M_NOUNI Names the global section a non-unique
name. By default,
PPL$CREATE_SHARED_MEMORY gives the
specified global section a name unique
to the application by using
PPL$UNIQUE_NAME. If you specified this
value to give the global section a
non-unique name when you called
PPL$CREATE_SHARED_MEMORY, you must
also specify it when you call
PPL$FLUSH_SHARED_MEM.
PPL$GET_INDEX
The Get Index of a Participant routine returns an index that is
unique within the application. A value of zero signifies the "top"
or "main" execution thread. The other processes in the application
always return an index greater than zero.
Format:
PPL$GET_INDEX participant-index
Arguments:
participant-index
VMS usage: longword_unsigned
type: longword (unsigned)
access: write only
mechanism: by reference
The index of the caller within this application. The
participant-index argument is the address of an unsigned longword
that contains this index. This index is assigned at process creation
time and is unique for each participant.
PPL$INCREMENT_SEMAPHORE
The Increment a Semaphore routine increments the value of the
semaphore by one, analogous to the signal protocol. If any other
participants have blocked on a call to PPL$DECREMENT_SEMAPHORE for
this semaphore, one is removed from the waiting queue and awakened.
Format:
PPL$INCREMENT_SEMAPHORE semaphore-id
Arguments:
semaphore-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Identifier of the semaphore. The semaphore-id argument is the
address of an unsigned longword containing the identifier.
PPL$INDEX_TO_PID
The Convert Participant Index to VMS Process Identifier routine
returns the VMS process identifier of the process or subprocess
associated with the specified index.
Format:
PPL$INDEX_TO_PID participant-index ,pid
Arguments:
participant-index
VMS usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
The index of the caller within this application. The
participant-index argument is the address of an unsigned longword
that contains this index. This index is assigned at the time of
process creation and is unique for each participant.
pid
VMS usage: longword_unsigned
type: longword (unsigned)
access: write only
mechanism: by reference
The process identifier of the VMS process associated with the
specified participant index. The pid argument is the address of an
unsigned longword that receives this process identifier.
PPL$INITIALIZE
The Initialize the PPL$ Facility routine informs the PPL$ facility
that the caller is forming or joining the parallel application. A
call to this service is entirely optional, since the PPL$ facility
will initialize itself at the first call to a PPL$ service.
Format:
PPL$INITIALIZE [size]
Arguments:
size
VMS usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
Number of pages allocated for the data structures required by the
PPL$ facility. The size argument is the address of an unsigned
longword containing this size. By default, the PPL$ facility
allocates PPL$K_INIT_SIZE (available to user programs as a link-time
constant) pages for its internal data structures. This initial
allocation provided by the PPL$ facility will accommodate a minimum
of 32 processes, 8 barriers, 8 semaphores, 4 events, and 16 global
sections. You can increase this allocation by specifying another
value.
PPL$INSERT_WORK_ITEM
The Insert a Work Queue Item routine inserts a work item into the
specified work queue.
Format
PPL$INSERT_WORK_ITEM queue-id, work-item [,flags] [,priority]
Arguments
queue-id
VMS Usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
The queue identifier. The queue-id argument is the address of an
unsigned longword containing the identifier.
work-item
VMS Usage: user_arg
type: longword (unsigned)
access: read only
mechanism: by value
A value to be entered into the queue. The work-item argument is an
unsigned longword containing this value. The content of work-item
is completely arbitrary. You may want to place single longword
values into work-item (for example, the number of a function
or task to be performed). You can also use work-item to pass a
pointer to a data block. (This data block must reside in memory
created by PPL$CREATE_SHARED_MEMORY or allocated from a shared
memory zone created by PPL$CREATE_VM_ZONE.)
flags
VMS Usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies options for inserting a work item into a work queue.
The optional flags argument is the address of a longword bit mask
containing the flag.
priority
VMS Usage: longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Specifies the priority of the item being inserted. The optional
priority argument is an unsigned longword containing the priority
value for the item to be inserted. If unspecified, the default
value is zero. A high numerical value indicates a high priority.
PPL$PID_TO_INDEX
The Convert VMS Process Identifier to Participant Index routine
returns the PPL$-defined participant index of the process or
subprocess associated with the specified VMS process identifier.
Format:
PPL$PID_TO_INDEX pid ,participant-index
Arguments:
pid
VMS usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
The process identifier of the VMS process whose participant index is
to be obtained. The pid argument is the address of an unsigned
longword containing this process identifier.
participant-index
VMS usage: longword_unsigned
type: longword (unsigned)
access: write only
mechanism: by reference
The participant-index of the process or subprocess associated with
the specified VMS process identifier. The participant-index
argument is the address of an unsigned longword that receives this
index. This index is assigned by the PPL$ facility at process
creation time and is unique for each participant.
PPL$READ_BARRIER
The Read a Barrier routine returns the specified barrier's current
quorum and the number of participants currently waiting (blocked) at
the barrier. The barrier must have been created by PPL$CREATE_BARRIER.
Format:
PPL$READ_BARRIER barrier-id ,quorum ,waiters
Arguments:
barrier-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Identifier of the specified event. The barrier-id argument is the
address of an unsigned longword containing the identifier.
Barrier-id is returned by PPL$CREATE_BARRIER.
quorum
VMS usage: word_signed
type: word (signed)
access: write only
mechanism: by reference
Number of participants required to terminate a wait for this barrier.
The quorum argument is the address of a signed word containing the
quorum value. This argument returns the current quorum value that
you set with PPL$CREATE_BARRIER, PPL$SET_QUORUM, or PPL$ADJUST_QUORUM.
waiters
VMS usage: word_signed
type: word (signed)
access: write only
mechansim: by reference
Number of participants currently waiting at this barrier. The waiters
argument is the address of a signed word containing the number of
waiting participants.
PPL$READ_EVENT
The Read an Event State routine returns the current state of the
specified event. The state can be occurred or not_occurred.
Format:
PPL$READ_EVENT event-id, occurred
Arguments:
event-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Identifier of the specified event. The event-id argument is the
address of an unsigned longword containing the identifier.
Event-id is returned by PPL$CREATE_EVENT.
occurred
VMS usage: longword_unsigned
type: longword (unsigned)
access: write only
mechanism: by reference
Receives the state of the specified event. The occurred argument is
the address of an unsigned longword that receives the event state.
This argument returns a value of true if the current state of the
event is occurred, and returns false if the current state of the
event is not_occurred.
PPL$READ_SEMAPHORE
The Read Semaphore Values routine returns the current and/or
maximum values of the specified counting semaphore.
Format:
PPL$READ_SEMAPHORE semaphore-id [,semaphore-value]
[,semaphore-maximum]
Arguments:
semaphore-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Identifier of the specified semaphore. The semaphore-id argument is
the address of an unsigned longword containing the identifier.
semaphore-value
VMS usage: word_signed
type: word (signed)
access: write only
mechanism: by reference
Value of the semaphore. The semaphore-value argument is the address
of a signed word containing the current value of the semaphore
specified by semaphore-id.
semaphore-maximum
VMS usage: word_unsigned
type: word (unsigned)
access: write only
mechanism: by reference
Maximum value of the semaphore. The semaphore-maximum argument is
the address of an unsigned word containing the maximum value of the
semaphore specified by semaphore-id.
PPL$READ_SPIN_LOCK
The Read a Spin Lock State routine returns the current state of a
spin lock. The state can be seized or not_seized.
Format
PPL$READ_SPIN_LOCK lock-id, seized
Arguments
lock-id
VMS Usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Identifier of the specified spin lock. The lock-id argument is the
address of an unsigned longword containing the identifier.
seized
VMS Usage: longword_unsigned
type: longword (unsigned)
access: write only
mechanism: by reference
Receives the state of the specified spin lock. The seized argument
is the address of an unsigned longword that receives the spin lock
state. This argument returns a value of true if the current state
of the spin lock is seized, and it returns a value of false if the
current state of the spin lock is not_seized.
PPL$READ_WORK_QUEUE
The Read a Work Queue routine returns information about a work
queue.
Format
PPL$READ_WORK_QUEUE queue-id [,queue-value]
Arguments
queue-id
VMS Usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
The queue identifier. The queue-id argument is the address of an
unsigned longword containing the identifier.
queue-value
VMS Usage: longword_signed
type: longword (signed)
access: write only
mechanism: by reference
Receives information about the specified work queue. If positive,
queue-value contains the number of items currently in the work
queue; if negative, it contains the number of processes currently
blocked (waiting for an item to be placed in the queue). If the
value returned is zero, there are no work items in the queue and
no blocked processes. The optional queue-value argument is the
address of a signed longword that receives the number of work
items or blocked processes.
PPL$RELEASE_SPIN_LOCK
The Release Spin Lock routine relinquishes the spin lock by clearing
the bit representing the lock. The lock must have been created by
PPL$CREATE_SPIN_LOCK.
Format:
PPL$RELEASE_SPIN_LOCK lock-id
Arguments:
lock-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Identifier of the specified lock. The lock-id argument is the
address of an unsigned longword containing the lock identifier.
PPL$REMOVE_WORK_ITEM
The Remove a Work Queue Item routine removes the next item in
order from a work queue.
Format
PPL$REMOVE_WORK_ITEM queue-id, work-item [,flags] [,spin]
Arguments
queue-id
VMS Usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
The queue identifier. The queue-id argument is the address of an
unsigned longword containing the identifier.
work-item
VMS Usage: user_arg
type: longword (unsigned)
access: write only
mechanism: by reference
Receives the value of the item that is removed from the work
queue. The work-item argument is the address of an unsigned
longword that receives the value of the item that is removed from
the work queue.
flags
VMS Usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies options for removing an item from the work queue. The
optional flags argument is the address of a longword bit mask
containing the flag. Valid values are as follows:
PPL$M_NON_BLOCKING If the specified work queue is empty,
return immediately with the
PPL$_NOT_AVAILABLE status indicating
that no items are available to be
removed from the work queue. By
default, if the work queue is empty,
the process hibernates until there is
an item available to be removed from
the work queue.
PPL$M_FROMTAIL Remove item from end (or tail) of the
work queue. By default, this routine
removes an item from the beginning (or
head) of the work queue.
PPL$M_SPIN_WAIT Indicates that the caller is never
to block, but rather to always spin
while waiting at this barrier.
PPL$M_SPIN_COUNTED Indicates that the caller wishes to spin
for a given amount of instructions and
then to block. The default is block
immediately, do not spin at all.
spin
VMS usage: mask_longword
type: long (unsigned)
access: read only
mechanism: by reference
This value must be specified when using the PPL$M_SPIN_COUNTED flag
and represents a relative time that a process will spin before
blocking.
PPL$RESET_EVENT
The Reset an Event routine resets an event's state to not_
occurred.
Format
PPL$RESET_EVENT event-id
Arguments
event-id
VMS Usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Identifier of the event. The event-id argument is the address of
an unsigned longword containing the identifier.
PPL$SEIZE_SPIN_LOCK
The Seize Spin Lock routine retrieves a simple (spin) lock by
waiting in a spin loop until the lock is free. The lock must have
been created by PPL$CREATE_SPIN_LOCK.
Format:
PPL$SEIZE_SPIN_LOCK lock-id [,flags]
Arguments:
lock-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Identifier of the lock to be seized. The lock-id argument is the
address of an unsigned longword containing the lock identifier.
flags
VMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies options for the seize lock operation. The flags argument
is a longword bit mask containing the flag. Valid flag vlaues are:
PPL$M_NON_BLOCKING The caller requests that the semaphore
be decremented if and only if it can
be done without causing the caller to
block. (This can be useful in
situations where the cost of waiting
for a resource is not desirable, or if
the caller merely intends to request
immediate access to any one of a
number of resources.)
PPL$SET_SEMAPHORE_MAXIMUM
The Set a Semaphore Maximum routine dynamically sets the maximum
value of a semaphore.
Format
PPL$SET_SEMAPHORE_MAXIMUM semaphore-id, semaphore-maximum
Arguments
semaphore-id
VMS Usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Identifier of the semaphore. The semaphore-id argument is the
address of an unsigned longword containing the identifier.
semaphore-maximum
VMS Usage: word_signed
type: word (signed)
access: read only
mechanism: by reference
New maximum value of the semaphore. The semaphore-maximum argument
is the address of a signed word containing the maximum value. This
value must be nonnegative.
PPL$SET_QUORUM
The Set Barrier Quorum routine establishes an initial value for the
specified barrier's quorum. This allows for easy re-use of a barrier
for different work items with different numbers of participants.
Format:
PPL$SET_QUORUM barrier-id ,quorum
Arguments:
barrier-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Identifier of the barrier. The barrier-id argument is the address of
the barrier identifier.
quorum
VMS usage: word_signed
type: word (signed)
access: read only
mechanism: by reference
The number of participants that are required to terminate an active
wait for this barrier. The quorum argument is the address of a
signed word that contains this quorum value. For example, a quorum
value of 3 indicates that the first two callers of
PPL$WAIT_AT_BARRIER who specify this barrier-id will be blocked
until a third caller issues that request. At that point, all three
will be released for further processing. This value must be
positive.
PPL$SPAWN
The Initiate Parallel Execution routine executes code in parallel
with the caller by creating one or more subordinate threads of
execution (VMS subprocesses).
Format
PPL$SPAWN copies [,program-name] [,children-ids] [,flags]
[,std-input-file] [,std-output-file]
Arguments
copies
VMS Usage: longword_unsigned
type: longword (unsigned)
access: modify
mechanism: by reference
Number of subordinates of the specified program to be executed
concurrently. The copies argument is the address of an unsigned
longword containing this number. Its value must be positive.
If you specify a value greater than 1 for the copies argument,
each copy created will have the same subprocess information (for
example, standard input and output files). If you want to specify
different information for each subprocess, call PPL$SPAWN once for
each subprocess.
On output, this parameter contains the number of subordinates
actually created. This value differs from the requested number
if an individual spawn attempt fails, for example, because of
insufficient quotas.
program-name
VMS Usage: logical_name
type: character string
access: read only
mechanism: by descriptor, fixed-length
Name of the program (image) to be invoked. The program-name
argument is the address of a descriptor pointing to a character
string containing the file specification of the image. Program-
name must have no more than 63 characters. If program-name
contains a logical name, the equivalence name must be in a logical
name table that the created subordinate can access. If you do not
specify a program-name, the default is to execute in parallel the
image being run by the caller.
children-ids
VMS Usage: vector_longword_unsigned
type: longword (unsigned)
access: write only
mechanism: by reference, array reference
Identifiers of each of the newly created subordinates. The
children-ids argument is the address of a vector of longwords
into which is written the index within the executing application
of each subordinate successfully initiated by this call.
flags
VMS Usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Bit mask specifying options for creating processes. The flags
argument is a longword bit mask containing the flags.
std-input-file
VMS Usage: logical-name
type: character string
access: read only
mechanism: by descriptor
File name of the file to serve as the standard input file in the
created subordinates. The std-input-file argument is the address
of a descriptor pointing to a character string containing the
file name. If you do not specify a value for this argument, the
subordinate inherits the creating participant's standard input
file (SYS$INPUT).
std-output-file
VMS Usage: logical-name
type: character string
access: read only
mechanism: by descriptor
File name of the file to serve as the standard output file in the
created subordinates. The std-output-file argument is the address
of a descriptor pointing to a character string containing the
file name. If you do not specify a value for this argument, the
subordinate inherits the creating participant's standard output
file (SYS$OUTPUT).
PPL$STOP
The Stop a Participant routine terminates the execution of the
specified participant in this application.
Format:
PPL$STOP participant-index
Arguments:
participant-index
VMS usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
Index of the participant to be terminated. The participant-index
argument is the address of the PPL$-defined index of the participant
to be terminated, as obtained by a call to PPL$SPAWN or
PPL$GET_INDEX.
PPL$TERMINATE
The Terminate PPL$ Participation routine ends the caller's
participation in the application "prematurely"; that is, at some
time before the caller is actually completing its execution.
Format:
PPL$TERMINATE [flags]
Arguments:
flags
VMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies options for terminating access to PPL$. The flags argument
is the address of a longword bit mask containing the flag. The flags
argument accepts the following value:
PPL$M_ABORT_CHILDREN Terminates all subordinates created by
the caller before returning from this
call. (PPL$ makes no effort to delete
children at process termination in the
absence of a call to this service, but
note that a VMS subprocess is deleted
when the parent terminates.)
PPL$TRIGGER_EVENT
The Trigger an Event routine causes the event's state to become
occurred. This results in processing any requests queued to the
event, so that any enabled ASTs and/or signals are delivered, and
anyone blocked is awakened.
Format:
PPL$TRIGGER_EVENT event-id [,event-parameter] [,flags]
Arguments:
event-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Identifier of the event. The event-id argument is the address of an
unsigned longword containing the identifier.
event-parameter
VMS usage: user_arg
type: longword (unsigned)
access: read only
mechanism: by value
Arbitrary value to be passed to all requests queued to the event at
the time of trigger or, if there are no queued event notification
requests for this event, to the first caller to enable event
notification. The event-parameter argument contains the value of an
unsigned longword containing this arbitrary value. Note that this
argument will not overwrite a parameter specified by a call that
enables the notification.
flags
VMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies options for triggering an event. The flags argument
is the value of a longword bit mask containing the flag. The
valid value for flags is as follows:
PPL$M_NOTIFY_ONE Processes exactly one enabled event
notification. By default, all pending
actions are processed when the event
state becomes occurred.
PPL$UNIQUE_NAME
The Produce a Unique Name routine returns an application-unique
name. A system-unique string specific to the calling application is
appended to the string specified by the user. The resulting name
will be identical for all participants in the application, but
different from all other applications on that system.
Format:
PPL$UNIQUE_NAME name-string ,resultant-string
[,resultant-length] [,flags]
Arguments:
name-string
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
The user-supplied string supplied for formation of the unique name.
The name-string argument is the address of a descriptor pointing to
this name.
resultant-string
VMS usage: char_string
type: character string
access: write only
mechanism: by descriptor
Resulting unique name that consists of the name-string string and
an appended system-unique string. The resultant-string argument is
the address of a descriptor pointing to this string.
resultant-length
VMS usage: word_unsigned
type: word (unsigned)
access: write only
mechanism: by reference
Length of the unique name returned as the resultant-string. The
resultant-length argument is the address of an unsigned word
containing this length.
flags
VMS Usage: word_longword
type: longword (unsigned)
access: write only
mechanism: by reference
Specifies whether the supplied name should be unique to the
application, the to calling process, or to this particular call.
The default is application-unique. Valid values are as follows:
PPL$M_PROC_UNIQUE Indicates that the caller wishes the
returned name to be unique to the
calling process.
PPL$M_PROC_UNIQUE Indicates that the caller wishes the
returned name to be unique to this
particular call.
PPL$WAIT_AT_BARRIER
The Synchronize at a Barrier routine causes the caller to wait at
the specified barrier. The barrier is in effect from the time the
first participant calls PPL$WAIT_AT_BARRIER for that barrier until
each member of the quorum has issued the call. At that time, the
wait concludes and all are released for further execution.
Format:
PPL$WAIT_AT_BARRIER barrier-id ,flags ,spin
Arguments:
barrier-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Identifier of the barrier. The barrier-id argument is the address
of an unsigned longword containing the barrier identifier.
flags
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies options for the wait at barrier operation. The flags
argument is the value of a longword bit mask containing the flag.
The bit, when set, specifies the corresponding option. Valid values
are as follows:
PPL$M_SPIN_WAIT Indicates that the caller is never
to block, but rather to always spin
while waiting at this barrier.
PPL$M_SPIN_COUNTED Indicates that the caller wishes to spin
for a given amount of instructions and
then to block. The default is block
immediately, do not spin at all.
spin
VMS usage: identifier
type: long (unsigned)
access: read only
mechanism: by reference
This value must be specified when using the PPL$M_SPIN_COUNTED flag
and represents a relative time that a process will spin before
blocking.
SMG$
Additional information available:
SMG$ADD_KEY_DEFSMG$BEGIN_DISPLAY_UPDATESMG$BEGIN_PASTEBOARD_UPDATE
SMG$CANCEL_INPUTSMG$CHANGE_PBD_CHARACTERISTICSSMG$CHANGE_RENDITION
SMG$CHANGE_VIEWPORTSMG$CHANGE_VIRTUAL_DISPLAYSMG$CHECK_FOR_OCCLUSION
SMG$CONTROL_MODESMG$COPY_VIRTUAL_DISPLAYSMG$CREATE_KEY_TABLE
SMG$CREATE_MENUSMG$CREATE_PASTEBOARDSMG$CREATE_SUBPROCESS
SMG$CREATE_VIRTUAL_DISPLAYSMG$CREATE_VIRTUAL_KEYBOARD
SMG$CREATE_VIEWPORTSMG$CURSOR_COLUMNSMG$CURSOR_ROW
SMG$DEFINE_KEYSMG$DEL_TERM_TABLESMG$DELETE_CHARS
SMG$DELETE_KEY_DEFSMG$DELETE_LINESMG$DELETE_MENU
SMG$DELETE_PASTEBOARDSMG$DELETE_SUBPROCESSSMG$DELETE_VIEWPORT
SMG$DELETE_VIRTUAL_DISPLAYSMG$DELETE_VIRTUAL_KEYBOARD
SMG$DISABLE_BROADCAST_TRAPPINGSMG$DISABLE_UNSOLICITED_INPUT
SMG$DRAW_CHARACTERSMG$DRAW_LINESMG$DRAW_RECTANGLE
SMG$ENABLE_UNSOLICITED_INPUTSMG$END_DISPLAY_UPDATE
SMG$END_PASTEBOARD_UPDATESMG$ERASE_CHARSSMG$ERASE_COLUMN
SMG$ERASE_DISPLAYSMG$ERASE_LINESMG$ERASE_PASTEBOARD
SMG$EXECUTE_COMMANDSMG$FIND_CURSOR_DISPLAYSMG$FLUSH_BUFFER
SMG$GET_BROADCAST_MESSAGESMG$GET_CHAR_AT_PHYSICAL_CURSOR
SMG$GET_DISPLAY_ATTRSMG$GET_KEY_DEFSMG$GET_KEYBOARD_ATTRIBUTES
SMG$GET_NUMERIC_DATASMG$GET_PASTEBOARD_ATTRIBUTES
SMG$GET_PASTING_INFOSMG$GET_TERM_DATASMG$GET_VIEWPORT_CHAR
SMG$HOME_CURSORSMG$INIT_TERM_TABLESMG$INIT_TERM_TABLE_BY_TYPE
SMG$INSERT_CHARSSMG$INSERT_LINESMG$INVALIDATE_DISPLAY
SMG$KEYCODE_TO_NAMESMG$LABEL_BORDERSMG$LIST_KEY_DEFS
SMG$LIST_PASTING_ORDERSMG$LOAD_KEY_DEFSSMG$LOAD_VIRTUAL_DISPLAY
SMG$MOVE_TEXTSMG$MOVE_VIRTUAL_DISPLAYSMG$NAME_TO_KEYCODE
SMG$PASTE_VIRTUAL_DISPLAYSMG$POP_VIRTUAL_DISPLAYSMG$PRINT_PASTEBOARD
SMG$PUT_CHARSSMG$PUT_CHARS_HIGHWIDESMG$PUT_CHARS_MULTI
SMG$PUT_CHARS_WIDESMG$PUT_HELP_TEXTSMG$PUT_LINE
SMG$PUT_LINE_HIGHWIDESMG$PUT_LINE_MULTISMG$PUT_LINE_WIDE
SMG$PUT_PASTEBOARDSMG$PUT_STATUS_LINESMG$READ_COMPOSED_LINE
SMG$READ_FROM_DISPLAYSMG$READ_KEYSTROKESMG$READ_STRING
SMG$READ_VERIFYSMG$REMOVE_LINESMG$REPAINT_LINESMG$REPAINT_SCREEN
SMG$REPASTE_VIRTUAL_DISPLAYSMG$REPLACE_INPUT_LINE
SMG$RESTORE_PHYSICAL_SCREENSMG$RETURN_CURSOR_POS
SMG$RETURN_INPUT_LINESMG$RING_BELLSMG$SAVE_PHYSICAL_SCREEN
SMG$SAVE_VIRTUAL_DISPLAYSMG$SCROLL_DISPLAY_AREASMG$SCROLL_VIEWPORT
SMG$SELECT_FROM_MENUSMG$SET_BROADCAST_TRAPPING
SMG$SET_CURSOR_ABSSMG$SET_CURSOR_MODESMG$SET_CURSOR_REL
SMG$SET_DEFAULT_STATESMG$SET_DISPLAY_SCROLL_REGION
SMG$SET_KEYPAD_MODESMG$SET_OUT_OF_BAND_ASTSSMG$SET_PHYSICAL_CURSOR
SMG$SET_TERM_CHARACTERISTICSSMG$SNAPSHOTSMG$UNPASTE_VIRTUAL_DISPLAY
SMG$ADD_KEY_DEF
The Add Key Definition routine adds a keypad key definition to a
table of key definitions.
Format:
SMG$ADD_KEY_DEF key-table-id ,key-name [,if-state] [,attributes]
[,equivalence-string] [,state-string]
Arguments:
key-table-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Identifies the key table to which you are adding a key definition.
The key-table-id argument is the address of an unsigned longword
that contains the key table identifier.
key-name
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
Identifies the key whose value you are defining. The key-name
argument is the address of a descriptor pointing to this key name.
The SMG$ADD_KEY_DEF procedure changes the string to uppercase and
removes trailing blanks.
if-state
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
Qualifies the value returned when key-name is struck. The if-state
argument is the address of a descriptor pointing to the state
string.
attributes
VMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Longword bit mask specifying additional attributes of this key
definition. The attributes argument is the address of an unsigned
longword that contains this attribute mask. If omitted, the mask is
zero.
equivalence-string
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
Character string to be substituted for the keystroke in the returned
line. The equivalence-string argument is the address of a
descriptor pointing to this equivalence string.
state-string
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
Contains a new state name which becomes the current state when this
key is pressed. The state-string argument is the address of a
descriptor pointing to the new state string.
SMG$BEGIN_DISPLAY_UPDATE
The Begin Batching of Display Updates routine saves, or batches, all
output to a virtual display until a matching call to
SMG$END_DISPLAY_UPDATE is encountered.
Format:
SMG$BEGIN_DISPLAY_UPDATE display-id
Argument
display-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the virtual display for which output is to be batched.
The display-id argument is the address of an unsigned longword that
contains the display identifier.
SMG$BEGIN_PASTEBOARD_UPDATE
The Begin Batching of Pasteboard Updates routine saves, or batches,
all output to a pasteboard until a matching call to
SMG$END_PASTEBOARD_UPDATE is encountered.
Format:
SMG$BEGIN_PASTEBOARD_UPDATE pasteboard-id
Argument
pasteboard-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the pasteboard for which output is to be batched. The
pasteboard-id argument is the address of an unsigned longword that
contains the pasteboard identifier. Pasteboard-id is returned by
SMG$CREATE_PASTEBOARD.
SMG$CANCEL_INPUT
The Cancel Input Request routine immediately cancels any
read-in-progress that was issued by SMG$READ_COMPOSED_LINE,
SMG$READ_KEYSTROKE, SMG$READ_STRING or SMG$READ_VERIFY.
Format:
SMG$CANCEL_INPUT keyboard-id
Argument
keyboard-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the virtual keyboard for which the input is to be
cancelled. The keyboard-id argument is the address of an unsigned
longword that contains the keyboard identifier. Keyboard-id is
returned by SMG$CREATE_VIRTUAL_KEYBOARD.
SMG$CHANGE_PBD_CHARACTERISTICS
The Change Pasteboad Characteristics routine lets you change the
characteristics associated with a pasteboard.
Format:
SMG$CHANGE_PBD_CHARACTERISTICS pasteboard-id [,desired-width]
[,width] [,desired-height] [,height]
[,desired-background-color] [,background-color]
Arguments:
pasteboard-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the pasteboard whose characteristics are to be changed.
The pasteboard-id argument is the address of an unsigned longword
that contains the pasteboard identifier.
desired-width
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
New width for the pasteboard. The desired-width argument is the
address of a signed longword that contains the desired width. If
omitted, the width does not change.
width
VMS usage: longword_signed
type: longword integer (signed)
access: write only
mechanism: by reference
Receives the physical width of the pasteboard. The width argument
is the address of a signed longword into which is written the actual
width of the pasteboard.
desired-height
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
New height for the pasteboard. The desired-height argument is the
address of a signed longword integer that contains the desired
height of the pasteboard. If omitted, the height does not change.
height
VMS usage: longword_signed
type: longword integer (signed)
access: write only
mechanism: by reference
Receives the physical height of the pasteboard. The height argument
is the address of a signed longword into which is written the actual
height of the pasteboard.
desired-background-color
VMS usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
Symbolic name for the desired background color. The
desired-background-color argument is the address of an unsigned
longword that contains the desired color.
background-color
VMS usage: longword_unsigned
type: longword (unsigned)
access: write only
mechanism: by reference
Receives the actual background color chosen. The background-color
argument is the address of an unsigned longword into which is
written the actual background color.
SMG$CHANGE_RENDITION
The Change Default Rendition routine changes the video attributes
for all or part of a virtual display.
Format:
SMG$CHANGE_RENDITION display-id ,start-row ,start-column
,number-of-rows ,number-of-columns [,rendition-set]
[,rendition-complement]
Arguments:
display-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the virtual display whose default rendition is to be
changed. The display-id argument is the address of an unsigned
longword that contains the display identifier.
start-row
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Starting row position to receive the new rendition. The start-row
argument is the address of a signed longword integer that contains
the number of the starting row.
start-column
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Starting column position to receive the new rendition. The
start-column argument is the address of a signed longword integer
that contains the number of the starting column.
number-of-rows
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Number of rows to receive the new rendition. The number-of-rows
argument is the address of a signed longword integer that contains
the number of rows to be affected.
number-of-columns
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Number of columns to receive the new rendition. The
number-of-columns argument is the address of a signed longword
integer that contains the number of columns to be affected.
rendition-set
VMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Mask which denotes video attributes for the specified portion of the
virtual display. The rendition-set argument is the address of an
unsigned longword whose bits control the video rendition. Each bit
in this argument affects the corresponding attribute in the display.
rendition-complement
VMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Mask which denotes video attributes for the specified portion of the
virtual display. The rendition-complement argument is the address
of an unsigned longword whose bits control the video rendition.
SMG$CHANGE_VIEWPORT
The Change the Viewport Associated with a Virtual Display routine
changes the size of an existing viewport into a virtual display.
The text which is currently in the viewport is remapped to fit the
new dimensions.
Format:
SMG$CHANGE_VIEWPORT display-id [,viewport-row-start]
[,viewport-column-start] [,viewport-number-rows]
[,viewport-number-columns]
Arguments:
display-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Identifier of the virtual display containing the viewport to be
changed. The display-id argument is the address of an unsigned
longword containing this identifier.
viewport-row-start
VMS usage: longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Optional row number in the virtual display that will become row 1 in
the changed viewport. The viewport-row-start argument is the
address of a signed longword containing the row number. If omitted,
the present viewport-row-start value is used.
viewport-column-start
VMS usage: longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Optional column number in the virtual display that will become
column 1 in the changed viewport. The viewport-column-start
argument is the address of a signed longword containing the column
number. If omitted, the present viewport-column-start value is
used.
viewport-number-rows
VMS usage: longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Optional number of rows in the changed viewport. The
viewport-number-rows argument is the address of a signed longword
containing the number of rows. If omitted, the present
viewport-number-rows value is used.
viewport-number-columns
VMS usage: longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Optional number of columns in the changed viewport. The
viewport-number-columns argument is the address of a signed longword
containing the number of columns. If omitted, the present
viewport-number-columns value is used.
SMG$CHANGE_VIRTUAL_DISPLAY
The Change Virtual Display routine lets you change the dimensions,
border, and video attributes of a virtual display.
Format:
SMG$CHANGE_VIRTUAL_DISPLAY display-id ,number-of-rows
,number-of-columns [,display-attributes]
[,video-attributes] [,character-set]
Arguments:
display-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the virtual display whose attributes are to be changed.
The display-id argument is the address of an unsigned longword that
contains the display identifier.
number-of-rows
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Specifies the new number of rows for the virtual display. The
number-of-rows argument is the address of a signed longword integer
that contains the number of rows in the virtual display.
number-of-columns
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Specifies the new number of columns for the virtual display. The
number-of-columns argument is the address of a signed longword
integer that contains the number of columns in the virtual display.
display-attributes
VMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies whether the virtual display is bordered (the default).
The display-attributes argument is the address of an unsigned
longword that contains the display attributes mask.
video-attributes
VMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the default rendition to be applied to all output in a
virtual display, unless overridden by a call to a specific output
routine. The video-attributes argument is the address of an
unsigned longword that contains the video attributes mask.
character-set
VMS usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the default character set for all text in this virtual
display. The character-set argument is the address of an unsigned
longword that contains the character set specifier. At this time,
the only valid value is SMG$C_ASCII, which is also the default.
SMG$CHECK_FOR_OCCLUSION
The Check for Occlusion routine checks to see whether a virtual
display is covered by another virtual display.
Format:
SMG$CHECK_FOR_OCCLUSION display-id ,pasteboard-id
,occlusion-state
Arguments:
display-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the virtual display to be checked. The display-id
argument is the address of an unsigned longword that contains the
display identifier. Display-id is returned by
SMG$CREATE_VIRTUAL_DISPLAY.
pasteboard-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the pasteboard to be checked. The pasteboard-id argument
is the address of an unsigned longword that contains the pasteboard
identifier. Pasteboard-id is returned by SMG$CREATE_PASTEBOARD.
occlusion-state
VMS usage: longword_signed
type: longword integer (signed)
access: write only
mechanism: by reference
Receives the value denoting whether the display is occluded. The
occlusion-state argument is the address of a signed longword integer
into which the occlusion state is written. Occlusion-state is set
to 1 if the display is occluded or set to 0 if the display is not
occluded on the specified pasteboard. If the procedure does not
return SS$_NORMAL, the contents of occlusion-state are undefined.
SMG$CONTROL_MODE
The Control Mode routine controls the mode of the pasteboard. This
includes buffering, minimal updating, whether the screen is cleared
when the pasteboard is deleted, and whether tab characters are used
for screen formatting.
Format:
SMG$CONTROL_MODE pasteboard-id [,new-mode] [,old-mode]
[,buffer-size]
Arguments:
pasteboard-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the pasteboard to be changed. The pasteboard-id argument
is the address of an unsigned longword that contains the pasteboard
identifier. Pasteboard-id is returned by SMG$CREATE_PASTEBOARD.
new-mode
VMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the new control settings to be used. The optional
new-mode argument is the address of an unsigned longword that
contains the mode settings. A bit set to 1 forces that mode to be
employed while a bit set to 0 inhibits that mode of operation.
old-mode
VMS usage: mask_longword
type: longword (unsigned)
access: write only
mechanism: by reference
Receives the control settings that were in effect before calling
this procedure. The optional old-mode argument is the address of an
unsigned longword into which are written the former mode settings.
A bit set to 1 indicates that the specified mode was employed while
a bit set to 0 indicates that the mode was inhibited.
buffer-size
VMS usage: word_unsigned
type: word (unsigned)
access: read only
mechanism: by reference
Specifies the size of the buffer in bytes. The optional buffer-size
argument is the address of an unsigned word that contains the size
of the buffer. Buffer-size is used when buffering mode is enabled
(SMG$M_BUF_ENABLED). The default and minimum buffer size is 256
bytes. The maximum value is 65535. The buffer-size value depends
on UAF values and the sysgen parameter MAXBUF.
SMG$COPY_VIRTUAL_DISPLAY
The Copy a Virtual Display routine creates a copy of an existing
virtual display and assigns to it a new virtual display number.
Format:
SMG$COPY_VIRTUAL_DISPLAY current-display-id ,new-display-id
Arguments:
current-display-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Display identifier of the virtual display to be replicated. The
current-display-id argument is the address of the unsigned longword
that contains the display identifier.
new-display-id
VMS usage: identifier
type: longword (unsigned)
access: write only
mechanism: by reference
Receives the display identifier of the newly created virtual
display. The new-display-id argument is the address of the unsigned
longword that receives the new display identifier.
SMG$CREATE_KEY_TABLE
The Create Key Table routine creates a table for key definitions.
Format:
SMG$CREATE_KEY_TABLE key-table-id
Argument
key-table-id
VMS usage: identifier
type: longword (unsigned)
access: write only
mechanism: by reference
Receives the identifier of the newly-created key table. The
key-table-id argument is the address of an unsigned longword into
which is written the key table identifier.
SMG$CREATE_MENU
The Fill the Virtual Display with a Menu routine displays menu
choices in the virtual display indicated, starting at the specified
row.
Format:
SMG$CREATE_MENU display-id ,choices [,menu-type] [,flags]
[,row] [,rendition-set] [,rendition-complement]
Arguments:
display-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Display identifier of the virtual display in which the menu is
created. The display-id argument is the address of an unsigned
longword containing this identifier.
choices
VMS usage: static array of char_string
type: character string
access: read only
mechanism: by descriptor
Static array in which each element corresponds to an item to be
displayed in the menu. The choices argument is the address of a
descriptor pointing to this static array of character strings. Note
that blank menu items are ignored.
menu-type
VMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Optional bit mask specifying the type of menu to be displayed. The
menu-type argument is the address of a longword bit mask that
specifies this menu type. Valid values are as follows:
SMG$K_BLOCK The menu items are displayed in matrix
format (default).
SMG$K_VERTICAL Each menu item is displayed on its own line.
SMG$K_HORIZONTAL The menu items are displayed all on one
line.
flags
VMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Optional bit mask specifying the attributes to be used for the menu.
The flags argument is the address of a longword bit mask that
specifies these attributes. Valid values are as follows:
SMG$M_FIXED_FORMAT Each menu item is in a fixed length
field. The field is the size of
the largest menu item. The
default is compress.
SMG$M_DOUBLE_SPACE Double-spaced rows of menu items.
The default is single spaced.
row
VMS usage: longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Optional row number in the specified virtual display at which the
first menu item is displayed. The row argument is the address of a
signed longword that contains this row number. If row is omitted,
the first row of the virtual scrolling region is used.
rendition-set
VMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Optional attribute specifier. The rendition-set argument is the
address of a longword bit mask in which each one-bit attribute
causes the corresponding attribute to be used when writing out the
menu choices. The following attributes can be specified by the
rendition-set argument:
SMG$M_BLINK Displays characters blinking.
SMG$M_BOLD Displays characters in higher-than-normal
intensity (bolded).
SMG$M_REVERSE Displays characters in reverse video ---
that is, using the opposite default
rendition of the virtual display.
SMG$M_UNDERLINE Displays characters underlined.
SMG$M_USER1 through SMG$M_USER8 Displays user-defined
attributes.
rendition-complement
VMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Optional attribute complement specifier. The rendition-complement
argument is the address of a longword bit mask in which each one-bit
attribute causes the corresponding attribute to be complemented when
writing out the menu choices. All of the attributes that can be
specified with the rendition-set argument can be complemented with
the rendition-complement argument.
SMG$CREATE_PASTEBOARD
The Create Pasteboard routine creates a pasteboard and returns its
assigned pasteboard identifier.
Format:
SMG$CREATE_PASTEBOARD pasteboard-id [,output-device]
[,number-of-pasteboard-rows]
[,number-of-pasteboard-columns] [,flags]
[,type-of-terminal]
Arguments:
pasteboard-id
VMS usage: identifier
type: longword (unsigned)
access: write only
mechanism: by reference
Receives the identifier of the newly created pasteboard. The
pasteboard-id argument is the address of an unsigned longword into
which is written the new pasteboard identifier.
output-device
VMS usage: device_name
type: character string
access: read only
mechanism: by descriptor
Specifies the file specification or logical name to which the output
associated with this pasteboard will be written. The output-device
argument is the address of a descriptor that points to the name of
the output device. If omitted, output is sent to SYS$OUTPUT.
number-of-pasteboard-rows
VMS usage: longword_signed
type: longword integer (signed)
access: write only
mechanism: by reference
Receives the number of rows on the device specified in the
output-device argument. The number-of-pasteboard-rows argument is
the address of a signed longword integer into which is written the
number of rows on the specified device, which will be the number of
rows in the pasteboard.
number-of-pasteboard-columns
VMS usage: longword_signed
type: longword (signed)
access: write only
mechanism: by reference
Receives the number of columns on the device specified in the
output-device argument. The number-of-pasteboard-columns argument
is the address of a signed longword integer into which is written
the number of columns on the specified device.
flags
VMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Bit mask that specifies optional behavior. The flags argument is
the address of an unsigned longword that contains the flag. The
default action is to clear the screen. If the value of flags is
SMG$M_KEEP_CONTENTS, the screen is not initially cleared. The
Screen Management Facility works best when it can manage the entire
screen. Therefore, using SMG$M_KEEP_CONTENTS is discouraged.
type-of-terminal
VMS usage: longword_signed
type: longword (signed)
access: write only
mechanism: by reference
Receives the SMG$ internal device type to which the output
associated with this pasteboard will be written. The
type-of-terminal argument is the address of an unsigned longword
into which is written the terminal type.
SMG$CREATE_SUBPROCESS
The Create and Initialize a Subprocess routine creates a DCL
subprocess and associates it with a virtual display.
Format:
SMG$CREATE_SUBPROCESS display-id [,AST-routine]
[,AST-argument]
Arguments:
display-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Identifier of the virtual display with which the newly created
subprocess is associated. The display-id argument is the address of
an unsigned longword containing this identifier.
AST-routine
VMS usage: ast_procedure
type: procedure entry mask
access: call without stack unwinding
mechanism: by value
Optional address of an AST routine to be called when the currently
executing command completes. The AST-routine argument is the
address of the routine's procedure entry mask --- that is, the
address of the routine itself.
AST-argument
VMS usage: user_arg
type: longword (unsigned)
access: read only
mechanism: by value
Optional argument you supply to the AST routine. The AST-argument
parameter is an unsigned longword that contains the value to be
passed to the AST routine.
SMG$CREATE_VIRTUAL_DISPLAY
The Create Virtual Display routine creates a virtual display and
returns its assigned display id.
Format:
SMG$CREATE_VIRTUAL_DISPLAY number-of-rows ,number-of-columns
,display-id [,display-attributes]
[,video-attributes] [,character-set]
Arguments:
number-of-rows
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Specifies the number of rows in the newly created virtual display.
The number-of-rows argument is the address of a signed longword
integer that contains the desired number of rows.
number-of-columns
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Specifies the number of columns in the newly created virtual
display. The number-of-columns argument is the address of a signed
longword integer that contains the desired number of columns.
display-id
VMS usage: identifier
type: longword (unsigned)
access: write only
mechanism: by reference
Receives the display-id of the newly created virtual display. The
display-id argument is the address of an unsigned longword into
which is written the display identifier.
display-attributes
VMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Receives the current default display attributes. The optional
display-attributes argument is the address of an unsigned longword
into which the current display attributes are written.
video-attributes
VMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the default rendition to be applied to all output in this
virtual display unless overridden by a call to a specific output
routine (for example, SMG$CHANGE_RENDITION). The video-attributes
argument is the address of an unsigned longword that contains the
video attributes mask.
character-set
VMS usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the default character set for all text in this virtual
display. The character-set argument is the address of an unsigned
longword that contains the character set specifier. At this time,
the only valid value is SMG$C_ASCII, which is also the default.
SMG$CREATE_VIRTUAL_KEYBOARD
The Create Virtual Keyboard routine creates a virtual keyboard and
returns its assigned keyboard-id.
Format:
SMG$CREATE_VIRTUAL_KEYBOARD keyboard-id [,input-device]
[,default-filespec] [,resultant-filespec]
[,recall-size]
Arguments:
keyboard-id
VMS usage: identifier
type: longword (unsigned)
access: write only
mechanism: by reference
Receives the keyboard identifier of the newly created virtual
keyboard. The keyboard-id argument is the address of an unsigned
longword into which is written the keyboard identifier.
input-device
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
String containing the file specification or logical name of the file
or terminal to be used for this virtual keyboard. The input-device
argument is the address of a descriptor pointing to the file
specification. If omitted, this defaults to SYS$INPUT.
default-filespec
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
String containing the default file specification. The
default-filespec argument is the address of a descriptor pointing to
the default file specification. If omitted, the null string is
used.
resultant-filespec
VMS usage: char_string
type: character string
access: write only
mechanism: by descriptor
String into which the procedure writes the fully expanded file
specification of the file used. The resultant-filespec argument is
the address of a descriptor pointing to the string into which is
written the file specification that was used.
recall-size
VMS usage: byte_unsigned
type: byte (unsigned)
access: read only
mechanism: by reference
Number of input lines to be saved for later recall. The optional
recall-size argument is the address of an unsigned byte containing
the specified number of lines. A value of zero turns off input line
recall. By default, 20 lines are saved for later recall.
SMG$CREATE_VIEWPORT
The Create a Virtual Viewport routine creates a viewport and
associates it with a virtual display. The location and size of the
viewport are specified by the caller.
Format:
SMG$CREATE_VIEWPORT display-id ,viewport-row-start
,viewport-column-start ,viewport-number-rows
,viewport-number-columns
Arguments:
display-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Display identifier of the virtual display associated with the newly
created viewport. The display-id argument is the address of an
unsigned longword containing this identifier.
viewport-row-start
VMS usage: longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Row number in the virtual display that will become row 1 in the
viewport. The viewport-row-start argument is the address of a
signed longword containing the row number.
viewport-column-start
VMS usage: longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Column number in the virtual display that will become column 1 in
the viewport. The viewport-column-start argument is the address of
a signed longword containing the column number.
viewport-number-rows
VMS usage: longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Number of rows in the viewport. The viewport-number-rows argument
is the address of a signed longword containing the number of rows in
the newly created viewport.
viewport-number-columns
VMS usage: longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Number of columns in the viewport. The viewport-number-columns
argument is the address of a signed longword containing the number
of columns in the newly created viewport.
SMG$CURSOR_COLUMN
The Return Cursor Column Position routine returns the virtual
cursor's current column position in a specified virtual display.
Format:
SMG$CURSOR_COLUMN display-id
ARGUMENT
display-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
The display for which the column position is returned. The
display-id argument is the address of an unsigned longword that
contains the display identifier.
SMG$CURSOR_ROW
The Return Cursor Row Position routine returns the virtual cursor's
current row position in a specified virtual display.
Format:
SMG$CURSOR_ROW display-id
ARGUMENT
display-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
The display for which the row position is returned. The display-id
argument is the address of an unsigned longword that contains the
display identifier.
SMG$DEFINE_KEY
The Perform a DEFINE/KEY Command routine performs the DEFINE/KEY
command you provide.
Format:
SMG$DEFINE_KEY key-table-id ,command-string
Arguments:
key-table-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Identification of the key definition table for which the DEFINE/KEY
command is to be performed. The key-table-id argument is the
address of an unsigned longword that contains the key table
identifier.
command-string
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
String containing the DEFINE/KEY command to be performed. The
command-string argument is the address of a descriptor pointing to
the command to be performed.
SMG$DEL_TERM_TABLE
The Delete Terminal Table routine terminates access to TERMTABLE.EXE
and frees the associated virtual address space.
Format:
SMG$DEL_TERM_TABLE
NONE
SMG$DELETE_CHARS
The Delete Characters routine deletes characters in a virtual
display.
Format:
SMG$DELETE_CHARS display-id ,number-of-characters ,start-row
,start-column
Arguments:
display-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Identifies the virtual display from which characters are to be
deleted. The display-id argument is the address of an unsigned
longword integer that contains the display identifier.
number-of-characters
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Specifies the number of characters to be deleted. The
number-of-characters argument is the address of a signed longword
integer that contains the number of characters to be deleted.
start-row
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Specifies the row position at which to start the deletion. The
start-row argument is the address of a signed longword integer that
contains the row number at which to start the deletion.
start-column
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Specifies the column position at which to start the deletion. The
start-column argument is the address of a signed longword integer
that contains the column position at which to start the deletion.
SMG$DELETE_KEY_DEF
The Delete Key Definition routine deletes a key definition from a
specified table of key definitions.
Format:
SMG$DELETE_KEY_DEF key-table-id ,key-name [,if-state]
Arguments:
key-table-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Identifies the key table from which the key definition is deleted.
The key-table-id argument is the address of an unsigned longword
that contains the key table identifier.
key-name
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
String containing the name of the key whose definition is to be
deleted. The key-name argument is the address of a descriptor
pointing to the key name. Key-name is stripped of trailing blanks
and converted to uppercase before use.
if-state
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
String containing a state name which further qualifies key-name.
The if-state argument is the address of a descriptor pointing to the
state name. If omitted, the null state is used. Thus if a key has
several definitions depending on various values of if-state, this
routine lets you delete only one of those definitions.
SMG$DELETE_LINE
The Delete Line routine deletes lines from a virtual display.
Format:
SMG$DELETE_LINE display-id ,start-row [,number-of-rows]
Arguments:
display-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Identifies the virtual display from which lines are to be deleted.
The display-id argument is the address of an unsigned longword that
contains the display identifier.
start-row
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Specifies the first line to be deleted from the virtual display.
The start-row argument is the address of a signed longword integer
that contains the number of the first line to be deleted.
number-of-rows
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Specifies the number of lines to be deleted. The number-of-rows
argument is the address of a signed longword integer that contains
the number of lines to be deleted. If omitted, one line is deleted.
SMG$DELETE_MENU
The End Access to a Menu in the Virtual Display routine ends access
to the menu choices in the specified virtual display.
Format:
SMG$DELETE_MENU display-id [,flags]
Arguments:
display-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Identifier of the virtual display in which the menu choices are
displayed. The display-id argument is the address of an unsigned
longword containing this identifier.
flags
VMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Optional bit mask specifying possible actions to be taken when
deleting the menu. The flags argument is the address of a longword
bit mask specifying these options. At this time, the only valid
value is SMG$M_ERASE_MENU. If this option is specified, all rows
containing menu items are erased.
SMG$DELETE_PASTEBOARD
The Delete Pasteboard routine deletes a pasteboard.
Format:
SMG$DELETE_PASTEBOARD pasteboard-id [,flags]
Arguments:
pasteboard-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the pasteboard to be deleted. The pasteboard-id argument
is the address of an unsigned longword that contains the pasteboard
identifier.
flags
VMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Determines whether this routine clears the screen after deleting the
specified pasteboard. The flags argument is the address of an
unsigned longword that contains the flag. If flags is 1, the screen
is cleared; if 0, the screen is not cleared. If this argument is
omitted, the default is to clear the screen.
SMG$DELETE_SUBPROCESS
The Terminate a Subprocess routine deletes a subprocess that was
created with the SMG$CREATE_SUBPROCESS routine.
Format:
SMG$DELETE_SUBPROCESS display-id
Arguments:
display-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Identifier of the virtual display associated with the subprocess
being deleted. The display-id argument is the address of an
unsigned longword that contains this virtual display identifier.
SMG$DELETE_VIEWPORT
The Delete a Viewport routine deletes the specified viewport from
any pasteboards to which it is pasted.
Format:
SMG$DELETE_VIEWPORT display-id
Arguments:
display-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Identifier of the virtual display associated with the viewport to be
deleted. The display-id argument is the address of an unsigned
longword containing this identifier.
SMG$DELETE_VIRTUAL_DISPLAY
The Delete Virtual Display routine deletes a virtual display.
Format:
SMG$DELETE_VIRTUAL_DISPLAY display-id
Argument
display-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the virtual display to be deleted. The display-id
argument is the address of an unsigned longword that contains the
display identifier.
SMG$DELETE_VIRTUAL_KEYBOARD
The Delete Virtual Keyboard routine deletes a virtual keyboard.
Format:
SMG$DELETE_VIRTUAL_KEYBOARD keyboard-id
Argument
keyboard-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the virtual keyboard to be deleted. The keyboard-id
argument is the address of an unsigned longword that contains the
keyboard identifier.
SMG$DISABLE_BROADCAST_TRAPPING
The Disable Broadcast Trapping routine disables trapping of
broadcast messages for the specified terminal.
Format:
SMG$DISABLE_BROADCAST_TRAPPING pasteboard-id
Arguments:
pasteboard-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the pasteboard for the terminal to be affected. The
pasteboard-id argument is the address of an unsigned longword that
contains the pasteboard identifier.
SMG$DISABLE_UNSOLICITED_INPUT
The Disable Unsolicited Input routine disables the invocation of AST
routines for unsolicited input.
Format:
SMG$DISABLE_UNSOLICITED_INPUT pasteboard-id
ARGUMENT
pasteboard-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the keyboard (associated with the specified pasteboard)
for which unsolicited input is being disabled. The pasteboard-id
argument is the address of an unsigned longword that contains the
pasteboard identifier. Pasteboard-id is returned by
SMG$CREATE_PASTEBOARD.
SMG$DRAW_CHARACTER
The Draw a Character in a Virtual Display routine draws a character
at the specified position in a virtual display.
Format:
SMG$DRAW_CHARACTER display-id ,flags [,row] [,column]
[,rendition-set] [,rendition-complement]
Arguments:
display-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Identifier of the virtual display. The display-id argument is the
address of an unsigned longword containing this identifier.
flags
VMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Bit mask indicating the character to be drawn. The flags argument
is the address of this bit mask. The valid character values are as
follows:
o SMG$M_UP
o SMG$M_DOWN
o SMG$M_LEFT
o SMG$M_RIGHT
row
VMS usage: longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Optional row number specifying the row position at which the
specified character is drawn. The row argument is the address of a
signed longword containing the row number.
column
VMS usage: longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Optional column number specifying the column position at which the
specified character is drawn. The column argument is the address of
a signed longword containing the column number.
rendition-set
VMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Optional attribute specifier. The rendition-set argument is the
address of a longword bit mask. Each bit attribute in this argument
causes the corresponding attribute to be set in the display.
rendition-complement
VMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Optional attribute complement specifier. The rendition-complement
argument is the address of an unsigned longword that contains a
video attributes mask. Each bit attribute in this argument causes
the corresponding attribute to be set in the display. All of the
attributes that can be specified with the rendition-set argument can
be complemented with the rendition-complement argument.
SMG$DRAW_LINE
The Draw a Line routine draws a horizontal or vertical line.
Format:
SMG$DRAW_LINE display-id ,start-row ,start-column ,end-row
,end-column [,rendition-set] [,rendition-complement]
Arguments:
display-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the virtual display on which the line is to be drawn. The
display-id argument is the address of an unsigned longword that
contains the display identifier. Display-id is returned by
SMG$CREATE_VIRTUAL_DISPLAY.
start-row
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Specifies the row at which to begin drawing the line. The start-row
argument is the address of a signed longword integer that contains
the row number at which to begin drawing the line.
start-column
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Specifies the column at which to begin drawing the line. The
start-column argument is the address of a signed longword integer
that contains the column number at which to begin drawing the line.
end-row
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Specifies the row at which the drawn line ends. The end-row
argument is the address of a signed longword integer that contains
the row number at which the drawn line ends.
end-column
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Specifies the column at which the drawn line ends. The end-column
argument is the address of a signed longword integer that contains
the column number at which the drawn line ends.
rendition-set
VMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
A mask which denotes video attributes for the drawn line. The
rendition-set argument is the address of an unsigned longword that
contains a video attributes mask. Each bit attribute in this
argument causes the corresponding attribute to be set in the
display.
rendition-complement
VMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
A mask which denotes video attributes for the line drawn. The
rendition-complement argument is the address of an unsigned longword
that contains a video attributes mask. Each bit attribute in this
argument causes the corresponding attribute to be set in the
display. Video attributes which can be manipulated in this manner
are the same as those for the rendition-set argument.
SMG$DRAW_RECTANGLE
The Draw a Rectangle routine draws a rectangle.
Format:
SMG$DRAW_RECTANGLE display-id ,start-row ,start-column
,end-row ,end-column [,rendition-set]
[,rendition-complement]
Arguments:
display-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the virtual display on which the rectangle is to be drawn.
The display-id argument is the address of an unsigned longword that
contains the display identifier.
start-row
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Specifies the row number of the top left-hand corner of the
rectangle. The start-row argument is the address of a signed
longword integer that contains the row number of the top left-hand
corner of the rectangle.
start-column
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Specifies the column number of the top left-hand corner of the
rectangle. The start-column argument is the address of a signed
longword integer that contains the column number of the top
left-hand corner of the rectangle.
end-row
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Specifies the row number of the bottom right-hand corner of the
rectangle. The end-row argument is the address of a signed longword
integer that contains the row number of the bottom right-hand corner
of the rectangle.
end-column
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Specifies the column number of the bottom right-hand corner of the
rectangle. The end-column argument is the address of a signed
longword integer that contains the column number of the bottom
right-hand corner of the rectangle.
rendition-set
VMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Mask that denotes video attributes for the drawn line. The
rendition-set argument is the address of an unsigned longword that
contains a video attributes mask. Each bit attribute in this
argument causes the corresponding attribute to be set in the
display.
rendition-complement
VMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Mask that denotes video attributes for the line drawn. The
rendition-complement argument is the address of an unsigned longword
that contains a video attributes mask. Each bit attribute in this
argument causes the corresponding attribute to be set in the
display. Video attributes that can be manipulated in this manner
are the same as for the rendition-set argument.
SMG$ENABLE_UNSOLICITED_INPUT
The Enable Unsolicited Input routine detects unsolicited input and
calls an AST routine in response.
Format:
SMG$ENABLE_UNSOLICITED_INPUT pasteboard-id ,AST-routine
[,AST-argument]
Arguments:
pasteboard-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the pasteboard for which unsolicited input is being
enabled. The pasteboard-id argument is the address of an unsigned
longword that contains the pasteboard identifier. Pasteboard-id is
returned by SMG$CREATE_VIRTUAL_PASTEBOARD.
AST-routine
VMS usage: ast_procedure
type: procedure entry mask
access: read only
mechanism: by value
The address of an AST routine to be called upon receipt of
unsolicited input at the terminal. The AST-routine argument is the
address of the routine's procedure entry mask, that is, the address
of the routine itself. SMG$ENABLE_UNSOLICITED_INPUT detects the
presence of unsolicited input and calls the AST routine with six
arguments: the pasteboard-id, the AST-argument, R0, R1, PC, and
PSL.
AST-argument
VMS usage: user_arg
type: longword (unsigned)
access: read only
mechanism: by value
A value to be passed to the AST routine. The AST-argument argument
contains the value to be passed to the AST routine.
SMG$END_DISPLAY_UPDATE
The End Display Update routine ends update batching for a virtual
display.
Format:
SMG$END_DISPLAY_UPDATE display-id
Argument
display-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the virtual display to be affected. The display-id
argument is the address of a longword that contains the display
identifier.
SMG$END_PASTEBOARD_UPDATE
The End Pasteboard Update routine ends update batching for a
pasteboard.
Format:
SMG$END_PASTEBOARD_UPDATE pasteboard-id
ARGUMENT
pasteboard-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the pasteboard on which the batch count is to be
decremented. The pasteboard-id argument is the address of an
unsigned longword that contains the pasteboard identifier.
Pasteboard-id is returned by SMG$CREATE_PASTEBOARD. If the batch
count reaches 0, all buffered output for the specified pasteboard is
written out.
SMG$ERASE_CHARS
The Erase Characters routine erases characters in a virtual display
by replacing them with blanks.
Format:
SMG$ERASE_CHARS display-id ,number-of-characters ,start-row
,start-column
Arguments:
display-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the virtual display from which characters will be erased.
The display-id argument is the address of an unsigned longword that
contains the display identifier.
number-of-characters
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Specifies the number of characters to be replaced with blanks. The
number-of-characters argument is the address of a signed longword
integer that contains the number of characters to be replaced with
blanks.
start-row
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Specifies the row on which the erase operation begins. The
start-row argument is the address of a signed longword integer that
contains the number of the row at which the erasure is to begin.
start-column
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Specifies the column on which the erase operation begins. The
start-column argument is the address of a signed longword integer
that contains the number of the column at which the erasure is to
begin.
SMG$ERASE_COLUMN
The Erase Column From Display routine erases the specified portion
of the virtual display from the given position to the end of the
column.
Format:
SMG$ERASE_COLUMN display-id [,start-row] [,column-number]
[,end-row]
Arguments:
display-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Identifier of the virtual display to be affected. The display-id
argument is the address of an unsigned longword containing this
virtual display identifier.
start-row
VMS usage: longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Optional line number at which the erase operation begins. The
start-row argument is the address of a signed longword that contains
the specified line number. If this argument is omitted, the
column-number argument is ignored and the erase operation begins at
the current location of the virtual cursor for that virtual display.
column-number
VMS usage: longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Optional column number at which the erase operation begins. The
column-number argument is the address of a signed longword that
contains the specified column number. If this argument is omitted,
the start-row argument is ignored and the erase operation begins at
the current location of the virtual cursor for that virtual display.
end-row
VMS usage: longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Optional row number at which the erase operation ends. The end-row
argument is the address of a signed longword that contains the
specified row number.
SMG$ERASE_DISPLAY
The Erase Virtual Display routine erases all or part of a virtual
display by replacing text characters with blanks.
Format:
SMG$ERASE_DISPLAY display-id [,start-row] [,start-column]
[,end-row] [,end-column]
Arguments:
display-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the virtual display to be erased. The display-id argument
is the address of an unsigned longword that contains the display
identifier.
start-row
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Specifies the row at which the erase operation begins. The
start-row argument is the address of a signed longword integer that
contains the number of the row at which the erasure begins.
start-column
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Specifies the column at which the erase operation begins. The
start-column argument is the address of a signed longword integer
that contains the number of the column at which the erasure begins.
end-row
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Specifies the row at which the erase operation ends, that is, the
last row to be erased. The end-row argument is the address of a
signed longword integer that contains the number of the last row to
be erased.
end-column
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Specifies the column at which the erase operation ends, that is, the
last column to be erased. The end-column argument is the address of
a signed longword integer that contains the number of the last
column to be erased.
SMG$ERASE_LINE
The Erase Line routine erases all or part of a line in a virtual
display.
Format:
SMG$ERASE_LINE display-id [,start-row] [,start-column]
Arguments:
display-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the virtual display to be affected. The display-id
argument is the address of an unsigned longword that contains the
display identifier. Display-id is returned by
SMG$CREATE_VIRTUAL_DISPLAY.
start-row
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Specifies the line at which the erase operation starts. The
start-row argument is the address of a signed longword integer that
contains the number of the row at which the erasure starts. If
omitted, start-column is also ignored and the current cursor
position is used.
start-column
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Specifies the column at which the erase operation starts. The
start-column argument is the address of a signed longword integer
that contains the number of the column at which the erasure starts.
If omitted, start-row is also ignored and the current cursor
position is used.
SMG$ERASE_PASTEBOARD
The Erase Pasteboard routine erases a pasteboard; that is, it clears
the screen.
Format:
SMG$ERASE_PASTEBOARD pasteboard-id
ARGUMENT
pasteboard-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the pasteboard to be erased. The pasteboard-id argument
is the address of an unsigned longword that contains the pasteboard
identifier. Pasteboard-id is returned by SMG$CREATE_PASTEBOARD.
SMG$EXECUTE_COMMAND
The Execute Command in a Subprocess routine executes the specified
command in the subprocess created with the SMG$CREATE_SUBPROCESS
routine.
Format:
SMG$EXECUTE_COMMAND display-id ,command-desc [,flags]
[,ret-status]
Arguments:
display-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Display identifier of the virtual display with which the subprocess
is associated. The display-id argument is the address of an
unsigned longword containing this identifier.
command-desc
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
Command string. The command-desc argument is the address of a
descriptor pointing to the command string.
flags
VMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Optional bit mask that specifies optional behavior. The flags
argument is the address of an unsigned longword that contains the
bit mask. The valid values for the bit mask are as follows:
SMG$M_DATA_FOLLOWS Input data follows. The next call to
SMG$EXECUTE_COMMAND contains input
data for the currently executing
command. Do not specify this value
if this is the last input data item.
If you do specify this value,
ret-status is not returned.
SMG$M_SEND_EOF Send end-of-file marker. The
end-of-file marker is sent to the
subprocess.
ret-status
VMS usage: cond_value
type: longword (unsigned)
access: write only
mechanism: by reference
Optional status of the executed command, provided that the commands
are not being buffered. The ret-status argument is the address of
an unsigned longword containing this status.
SMG$FIND_CURSOR_DISPLAY
The Find Display that Contains the Cursor routine returns the
identifier of the most recently pasted virtual display that contains
the physical cursor.
Format:
SMG$FIND_CURSOR_DISPLAY pasteboard-id ,display-id
[,pasteboard-row] [,pasteboard-column]
Arguments:
pasteboard-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the pasteboard (physical screen) in which the cursor is to
be found. The pasteboard-id argument is the address of a longword
that contains the pasteboard identifier. Pasteboard-id is returned
by SMG$CREATE_PASTEBOARD.
display-id
VMS usage: identifier
type: longword (unsigned)
access: write only
mechanism: by reference
Receives the identifier of the display in which the cursor was
found. The display-id argument is the address of a longword into
which the display identifier is written.
pasteboard-row
VMS usage: longword_signed
type: longword (signed)
access: read only
mechanism: by reference
The row position at which to begin the search for the cursor. The
optional pasteboard-row argument is the address of a signed longword
containing the pasteboard row. You can use pasteboard-row instead
of the physical cursor row.
pasteboard-column
VMS usage: longword_signed
type: longword (signed)
access: read only
mechanism: by reference
The column position at which to begin the search for the cursor.
The optional pasteboard-column argument is the address of a signed
longword containing the pasteboard column. You can use
pasteboard-column instead of the physical cursor column.
SMG$FLUSH_BUFFER
The Flush Buffer routine flushes all buffered output to the
terminal.
Format:
SMG$FLUSH_BUFFER pasteboard-id
ARGUMENT
pasteboard-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the pasteboard to be flushed. The pasteboard-id argument
is the address of an unsigned longword that contains the pasteboard
identifier. Pasteboard-id is returned by SMG$CREATE_PASTEBOARD.
SMG$GET_BROADCAST_MESSAGE
The Get Broadcast Message routine determines whether a message has
been broadcast to the pasteboard and returns the message.
Format:
SMG$GET_BROADCAST_MESSAGE pasteboard-id [,message]
[,message-length] [,message-type]
Arguments:
pasteboard-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the terminal to be checked for the presence of a broadcast
message. The pasteboard-id argument is the address of an unsigned
longword that contains the pasteboard identifier. Pasteboard-id is
returned by SMG$CREATE_PASTEBOARD.
message
VMS usage: char_string
type: character string
access: write only
mechanism: by descriptor
A string that receives the broadcast message, if such a message is
available. The message argument is the address of a descriptor that
points to the storage into which the message text is written. If
this argument is omitted, the broadcast message is discarded.
message-length
VMS usage: word_unsigned
type: word integer (unsigned)
access: write only
mechanism: by reference
Receives the actual length of the broadcast message. The
message-length argument is the address of an unsigned word into
which is written the length of the message.
message-type
VMS usage: word_unsigned
type: word integer (unsigned)
access: write only
mechanism: by reference
Receives the type of broadcast message. The message-type argument
is the address of an unsigned word into which is written the type of
message. Values for message-type are defined by the $MSGDEF library
definition. If the value for message-type is not MSG$_TRMBRDCST,
the condition value returned is SMG$_NOBRDMSG.
SMG$GET_CHAR_AT_PHYSICAL_CURSOR
The Return Character At Cursor routine returns the character at the
current physical cursor position.
Format:
SMG$GET_CHAR_AT_PHYSICAL_CURSOR pasteboard-id ,character-code
Arguments:
pasteboard-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the pasteboard on which to retrieve the character. The
pasteboard-id argument is the address of a longword that contains
the pasteboard identifier.
character-code
VMS usage: byte_unsigned
type: byte (unsigned)
access: write only
mechanism: by reference
Returned character code. The character-code argument is the address
of an unsigned byte into which is written the character's ASCII
code.
SMG$GET_DISPLAY_ATTR
The Get Display Attributes routine returns the attributes associated
with a virtual display.
Format:
SMG$GET_DISPLAY_ATTR display-id [,height] [,width]
[,display-attributes] [,video-attributes]
[,character-set] [,flags]
Arguments:
display-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the virtual display for which information is requested.
The display-id argument is the address of an unsigned longword that
contains the display identifier. Display-id is returned by
SMG$CREATE_VIRTUAL_DISPLAY.
height
VMS usage: longword_signed
type: longword (signed)
access: write only
mechanism: by reference
Receives the number of rows in the display. The optional height
argument is the address of a signed longword integer into which the
height is written.
width
VMS usage: longword_signed
type: longword (signed)
access: write only
mechanism: by reference
Receives the number of columns in the display. The optional width
argument is the address of a signed longword integer into which is
written the number of columns in the display.
display-attributes
VMS usage: mask_longword
type: longword (unsigned)
access: write only
mechanism: by reference
Receives the current default display attributes. The optional
display-attributes argument is the address of an unsigned longword
into which the current display attributes are written.
video-attributes
VMS usage: mask_longword
type: longword (unsigned)
access: write only
mechanism: by reference
Receives the current default video attributes. The optional
video-attributes argument is the address of an unsigned longword
into which the current video attributes are written.
character-set
VMS usage: longword_unsigned
type: longword (unsigned)
access: write only
mechanism: by reference
Specifies the default character set for all text in this virtual
display. The optional character-set argument is the address of an
unsigned longword that specifies the character set. Valid values
are SMG$C_ASCII, the default, and SMG$C_SPEC_GRAPHICS.
flags
VMS usage: mask_longword
type: longword (unsigned)
access: write only
mechanism: by reference
Optional bit mask that receives the following information about the
specified display:
SMG$M_SUBPROCESS Display has a subprocess attached to it.
SMG$M_MENU Display contains a menu.
SMG$M_VIEWPORT Display contains a viewport.
SMG$GET_KEY_DEF
The Get Key Definition routine returns the key definition for a
specified key.
Format:
SMG$GET_KEY_DEF key-table-id ,key-name [,if-state]
[,attributes] [,equivalence-string] [,state-string]
Arguments:
key-table-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the key table from which you are extracting a definition.
The key-table-id argument is the address of an unsigned longword
that contains the key table identifier. Key-table-id is returned by
SMG$CREATE_KEY_TABLE.
key-name
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
Specifies the name of the key associated with the definition. The
key-name argument is the address of a descriptor pointing to the key
name.
if-state
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
Specifies the current state name in effect after the key is pressed.
The if-state argument is the address of a descriptor pointing to the
state name.
attributes
VMS usage: mask_longword
type: longword (unsigned)
access: write only
mechanism: by reference
Receives the attributes bit mask for this key definition. The
attributes argument is the address of a longword into which is
written the bit mask describing the key's attributes.
equivalence-string
VMS usage: char_string
type: character string
access: write only
mechanism: by descriptor
Receives the equivalence string for this key definition. The
equivalence-string argument is the address of a descriptor pointing
to the storage into which is written the equivalence string.
state-string
VMS usage: char_string
type: character string
access: write only
mechanism: by descriptor
Receives the new state name, if any, which is set by this key
definition. The state-string argument is the address of a
descriptor pointing to the storage into which is written the new
state string.
SMG$GET_KEYBOARD_ATTRIBUTES
The Get Keyboard Attributes routine gets information about a virtual
keyboard and leaves it in a user-supplied area: the keyboard
information table (KIT).
Format:
SMG$GET_KEYBOARD_ATTRIBUTES keyboard-id ,p-kit ,p-kit-size
Arguments:
keyboard-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Keyboard identifier. The keyboard-id argument is the address of an
unsigned longword containing the identification of the virtual
keyboard from which to read. A virtual-keyboard is created by
calling the SMG$CREATE_VIRTUAL_KEYBOARD routine.
p-kit
VMS usage: address
type: longword (unsigned)
access: write only
mechanism: by reference
Receives the keyboard information. The p-kit argument is the
address of an array of unsigned bytes into which are written the
keyboard attributes.
p-kit-size
VMS usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
Size of the keyboard information table. The p-kit-size argument is
the address of an unsigned longword containing the size of the KIT
in bytes.
SMG$GET_NUMERIC_DATA
The Get Numeric Terminal Data routine accesses TERMTABLE.EXE and
returns the numeric sequence that causes a terminal to perform a
specified operation.
Format:
SMG$GET_NUMERIC_DATA termtable-address ,request-code
,buffer-address
Arguments:
termtable-address
VMS usage: address
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the address of the TERMTABLE entry for the desired
terminal. The termtable-address argument is the address of an
unsigned longword that contains the address of TERMTABLE
information.
request-code
VMS usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
Request code which specifies the desired capability. The
request-code argument is an unsigned longword constant containing
this request code. The request code is of the form SMG$K_code where
code corresponds to a keyword in the terminal capabilities table,
for example, ANSI_CRT.
buffer-address
VMS usage: address
type: longword (unsigned)
access: write only
mechanism: by reference
Address of the first byte of the longword to which
SMG$GET_NUMERIC_DATA writes the numeric capability data. The
buffer-address argument is an unsigned longword which contains the
address of this buffer.
SMG$GET_PASTEBOARD_ATTRIBUTES
The Get Pasteboard Attributes routine gets pasteboard attributes and
stores them in the pasteboard information table.
Format:
SMG$GET_PASTEBOARD_ATTRIBUTES pasteboard-id
,pasteboard-info-table ,pasteboard-info-table-size
Arguments:
pasteboard-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the pasteboard for which information is requested. The
pasteboard-id argument is the address of an unsigned longword that
contains the pasteboard identifier.
pasteboard-info-table
VMS usage: vector_byte_unsigned
type: unspecified
access: write only
mechanism: by reference, array reference
Receives the pasteboard attributes. The pasteboard-info-table
argument is the address of a data structure into which are written
the pasteboard attributes.
pasteboard-info-table-size
VMS usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the number of bytes in the pasteboard-info-table. The
pasteboard-info-table-size argument is the address of an unsigned
longword that contains the size (in bytes) of the
pasteboard-info-table.
SMG$GET_PASTING_INFO
Provided that the specified virtual display is currently pasted, the
Return Pasting Information routine returns the row and column of the
pasting.
Format:
SMG$GET_PASTING_INFO display-id ,pasteboard-id ,flags
[,pasteboard-row] [,pasteboard-column]
Arguments:
display-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Identifier of the virtual display to be examined. The display-id
argument is the address of an unsigned longword containing the
identifier of this virtual display.
pasteboard-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Identifier of the pasteboard on which the virtual display is pasted.
The pasteboard-id argument is the address of an unsigned longword
containing the identifier of this pasteboard.
flags
VMS usage: mask_longword
type: longword (unsigned)
access: write only
mechanism: by reference
Flag indicating the status of the specified virtual display with
respect to the specified pasteboard. The flags argument is the
address of an unsigned longword indicating this status.
pasteboard-row
VMS usage: longword_signed
type: longword (signed)
access: write only
mechanism: by reference
Row of the pasteboard that contains row 1 of the specified virtual
display. The optional pasteboard-row argument is the address of a
signed longword containing the row number of the pasteboard row that
contains the first row of the virtual display.
pasteboard-column
VMS usage: longword_signed
type: longword (signed)
access: write only
mechanism: by reference
Column of the pasteboard that contains column 1 of the specified
virtual display. The optional pasteboard-column argument is the
address of a signed longword containing the column number of the
pasteboard column that contains the first column of the virtual
display.
SMG$GET_TERM_DATA
The Get Terminal Data routine accesses TERMTABLE.EXE and returns the
character sequence that causes a terminal to perform a specified
operation.
Format:
SMG$GET_TERM_DATA termtable-address ,request-code
,maximum-buffer-length ,return-length
,buffer-address [,input-argument-vector]
Arguments:
termtable-address
VMS usage: address
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the address of the TERMTABLE entry for the desired
terminal. The termtable-address argument is the address of an
unsigned longword that contains the address of TERMTABLE
information.
request-code
VMS usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
Longword constant of the form SMG$K_code, where code is the name of
the desired capability field. The request-code argument is the
address of an unsigned longword that contains the request code.
maximum-buffer-length
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Maximum length of the buffer into which the requested capability
data is written. The maximum-buffer-length argument is the address
of a signed longword integer that contains the maximum number of
bytes that can be written into the buffer.
return-length
VMS usage: longword_signed
type: longword integer (signed)
access: write only
mechanism: by reference
Receives the number of bytes actually written into the buffer. The
return-length argument is the address of a signed longword integer
into which is written the number of bytes transferred into the
buffer.
buffer-address
VMS usage: address
type: longword (unsigned)
access: write only
mechanism: by reference
Address of the first byte of the buffer which is to receive the
capability data. The buffer-address argument is an unsigned
longword that contains the address of the buffer.
input-argument-vector
VMS usage: vector_longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference, array reference
Address of a list of longwords used for capabilities that require a
variable number of arguments, and for those that require
substitution or arithmetic operations on an argument. The
input-argument-vector argument is the address of an array of
unsigned longwords that contains capability arguments. The first
longword must contain the number of arguments that follow.
SMG$GET_VIEWPORT_CHAR
The Get Characteristics of Display Viewport routine returns the
characteristics of the specified viewport.
Format:
SMG$GET_VIEWPORT_CHAR display-id [,viewport-row-start]
[,viewport-column-start] [,viewport-number-rows]
[,viewport-number-columns]
Arguments:
display-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Identifier of the virtual display associated with the viewport. The
display-id argument is the address of an unsigned longword
containing this identifier.
viewport-row-start
VMS usage: longword_signed
type: longword (signed)
access: write only
mechanism: by reference
Optional argument that receives the starting row number of the
viewport. The viewport-row-start argument is the address of a
signed longword that receives this row number.
viewport-column-start
VMS usage: longword_signed
type: longword (signed)
access: write only
mechanism: by reference
Optional argument that receives the starting column number of the
specified viewport. The viewport-column-start argument is the
address of a signed longword that receives this column number.
viewport-number-rows
VMS usage: longword_signed
type: longword (signed)
access: write only
mechanism: by reference
Optional argument that receives the number of rows in the specified
viewport. The viewport-number-rows argument is the address of a
signed longword that receives this number.
viewport-number-columns
VMS usage: longword_signed
type: longword (signed)
access: write only
mechanism: by reference
Optional argument that receives the number of columns in the
specified viewport. The viewport-number-columns argument is the
address of a signed longword that receives this number.
SMG$HOME_CURSOR
The Home Cursor routine moves the virtual cursor to the specified
corner of a virtual display.
Format:
SMG$HOME_CURSOR display-id [,position-code]
Arguments:
display-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the virtual display in which the virtual cursor is moved.
The display-id argument is the address of a longword that contains
the display identifier. Display-id is returned by
SMG$CREATE_VIRTUAL_DISPLAY.
position-code
VMS usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the point to which the virtual cursor moves. The
position-code argument is the address of a longword that contains
the position code.
SMG$INIT_TERM_TABLE
The Initialize Terminal Table routine initializes the TERMTABLE
database for the terminal named, so that subsequent calls to
SMG$GET_TERM_DATA can extract information and command strings for
that terminal.
Format:
SMG$INIT_TERM_TABLE terminal-name, termtable-address
Arguments:
terminal-name
VMS usage: device_name
type: character string
access: read only
mechanism: by descriptor
Specifies the name of the terminal. The terminal-name argument is
the address of a descriptor pointing to the terminal name. The name
must be an entry in TERMTABLE.EXE
termtable-address
VMS usage: address
type: longword (unsigned)
access: write only
mechanism: by reference
Address of the entry for a particular type of terminal in
TERMTABLE.EXE. The termtable-address argument is the address of an
unsigned longword that contains the address of TERMTABLE
information.
SMG$INIT_TERM_TABLE_BY_TYPE
The Initialize TERMTABLE by VMS Terminal Type routine initializes
the TERMTABLE database for the terminal named, so that subsequent
calls to SMG$GET_TERM_DATA can extract information and command
strings for that terminal.
Format:
SMG$INIT_TERM_TABLE_BY_TYPE terminal-type ,termtable-address
[,terminal-name]
Arguments:
terminal-type
VMS usage: byte_signed
type: byte integer (signed)
access: read only
mechanism: by reference
The device type of the terminal, as designated by a VMS symbolic
terminal type or by another value returned by the $GETDVI system
service. The terminal-type argument is the address of a signed byte
integer that contains the terminal type.
termtable-address
VMS usage: address
type: longword (unsigned)
access: write only
mechanism: by reference
Address of the entry for a particular type of terminal in
TERMTABLE.EXE. The termtable-address argument is the address of an
unsigned longword into which is written the address of a terminal
entry.
terminal-name
VMS usage: device_name
type: character string
access: write only
mechanism: by descriptor
A string into which is written the terminal name associated with the
device type. The terminal-name argument is the address of a
descriptor pointing to the storage into which the terminal name is
written.
SMG$INSERT_CHARS
The Insert Characters routine inserts characters into a virtual
display.
Format:
SMG$INSERT_CHARS display-id ,character-string ,start-row
,start-column [,rendition-set] [,rendition-complement]
[,character-set]
Arguments:
display-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the virtual display affected. The pasteboard-id argument
is the address of an unsigned longword that contains the pasteboard
identifier. Display-id is returned by SMG$CREATE_VIRTUAL_DISPLAY.
character-string
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
The character string to be inserted. The character-string argument
is the address of a descriptor that points to the string to be
inserted.
start-row
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
The row position at which to begin the insertion. The start-row
argument is the address of a signed longword integer that contains
the row number.
start-column
VMS usage: longword_signed
type: longword (signed)
access: read only
mechanism: by reference
The column position at which to begin the insertion. The
start-column argument is the address of a signed longword integer
that contains the column number.
rendition-set
VMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Attribute specifier. The optional rendition-set argument is the
address of a longword bit mask in which each 1-bit attribute causes
the corresponding attribute to be set in the display. The following
attributes can be specified using the rendition-set argument:
SMG$M_BLINK Displays blinking characters
SMG$M_BOLD Displays characters in higher-than-normal
intensity
SMG$M_REVERSE Displays characters in reverse video, that is,
using the opposite default rendition of the
virtual display
SMG$M_UNDERLINE Displays underlined characters
rendition-complement
VMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Attribute complement specifier. The optional rendition-complement
argument is the address of a longword bit mask in which each 1-bit
attribute causes the corresponding attribute to be complemented in
the display. All of the attributes that can be specified with the
rendition-set argument can be complemented with
rendition-complement. The display-id argument myst be specified
when using the rendition-complement argument.
character-set
VMS usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the default character set for all text in this virtual
display. The character-set argument is the address of an unsigned
longword that contains the character set code. At this time, the
only valid value is SMG$C_ASCII, which is also the default.
SMG$INSERT_LINE
The Insert Line routine inserts a line into a virtual display and
scrolls the display.
Format:
SMG$INSERT_LINE display-id ,start-row [,character-string]
[,direction] [,rendition-set] [,rendition-complement]
[,flags] [,character-set]
Arguments:
display-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the virtual display affected. The display-id argument is
the address of an unsigned longword that contains the display
identifier.
start-row
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Specifies the line number at which the string is inserted and at
which point scrolling begins. The start-row argument is the address
of a signed longword integer that contains the line number.
character-string
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
The character string to be inserted by SMG$INSERT_LINE. The
character-string argument is the address of a descriptor pointing to
this string.
direction
VMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the scrolling direction. The direction argument is the
address of a longword bit mask that contains the direction code.
Valid values are SMG$M_UP and SMG$M_DOWN. SMG$M_UP is the default.
rendition-set
VMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Attribute specifier. The optional rendition-set argument is the
address of a longword bit mask in which each 1-bit attribute causes
the corresponding attribute to be set in the display. The following
attributes can be specified using the rendition-set argument:
SMG$M_BLINK Displays blinking characters
SMG$M_BOLD Displays characters in higher-than-normal
intensity
SMG$M_REVERSE Displays characters in reverse video, that is,
using the opposite default rendition of the
virtual display
SMG$M_UNDERLINE Displays underlined characters
rendition-complement
VMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Attribute complement specifier. The optional rendition-complement
argument is the address of a longword bit mask in which each 1-bit
attribute causes the corresponding attribute to be complemented in
the display. All of the attributes that can be specified with the
rendition-set argument can be complemented with
rendition-complement. The display-id argument must be specified
when using the rendition-complement argument.
flags
VMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the action to take if the text does not fit on the line.
The flags argument is the address of an unsigned longword that
contains the flag. Zero specifies no wrap (the default) while 1
specifies wrap.
character-set
VMS usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the default character set for all text in this virtual
display. The character-set argument is the address of a longword
that contains the character set code. At this time, the only valid
value is SMG$C_ASCII, which is also the default.
SMG$INVALIDATE_DISPLAY
The Mark a Display as Invalid routine marks a display as invalid and
causes the entire display to be redrawn.
Format:
SMG$INVALIDATE_DISPLAY display-id
Argument
display-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the virtual display affected. The display-id argument is
the address of an unsigned longword that contains the display
identifier.
SMG$KEYCODE_TO_NAME
The Translate a Key Code Into a Key Name routine translates the key
code of a key on the keyboard into its associated key name.
Format:
SMG$KEYCODE_TO_NAME key-code ,key-name
Arguments:
key-code
VMS usage: word_signed
type: word (signed)
access: read only
mechanism: by reference
Specifies the key code to translate into a key name. The key-code
argument is the address of a signed word that contains the key code.
key-name
VMS usage: char_string
type: character string
access: write only
mechanism: by descriptor
String containing the name of the key into which key-code is to be
translated. The key-name argument is the address of a descriptor
pointing to the character string containing the key name. The
key-name argument is simply the name of the key, for example, COMMA,
PERIOD, KP4, and so forth.
SMG$LABEL_BORDER
The Label a Virtual Display Border routine supplies a label for a
virtual display's border.
Format:
SMG$LABEL_BORDER display-id [,text] [,position-code]
[,units] [,rendition-set] [,rendition-complement]
[,character-set]
Arguments:
display-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the virtual display affected. The display-id argument is
the address of an unsigned longword that contains the display
identifier.
text
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
The new label for this display's border. The text argument is the
address of a descriptor pointing to the label text. If omitted, the
display becomes unlabeled.
position-code
VMS usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies which of the display's borders contains the label. The
position-code argument is the address of an unsigned longword that
contains the position code.
units
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Specifies the character position at which the label begins within
the border. The units argument is the address of a signed longword
integer that contains the character position. If omitted, the label
is centered in the specified border.
rendition-set
VMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Mask which denotes video attributes for the drawn line. The
rendition-set argument is the address of an unsigned longword that
contains a video attributes mask. Each bit attribute in this
argument causes the corresponding attribute to be set in the
display.
rendition-complement
VMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
A mask which denotes video attributes for the line drawn. The
rendition-complement argument is the address of an unsigned longword
that contains a video attributes mask. Each bit attribute in this
argument causes the corresponding attribute to be set in the
display. Video attributes which can be manipulated in this manner
are the same as those for the rendition-set argument.
character-set
VMS usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the default character set for all text in this virtual
display. The character-set argument is the address of an unsigned
longword that contains the character set code. At this time, the
only valid value is SMG$C_ASCII, which is also the default.
SMG$LIST_KEY_DEFS
The List Key Definitions routine returns the definition (equivalence
string) associated with a specified key in a specified key table.
Format:
SMG$LIST_KEY_DEFS key-table-id ,context [,key-name] [,if-state]
[,attributes] [,equivalence-string] [,state-string]
Arguments:
key-table-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the key table from which you are extracting a key
definition. The key-table-id argument is the address of an unsigned
longword that contains the key table identifier.
context
VMS usage: context
type: longword (unsigned)
access: modify
mechanism: by reference
Provides a means to extract a series of key definitions from a key
table. The context argument is the address of a signed longword
integer that contains the context variable. For the first call to
this routine, you should set the context argument to zero.
key-name
VMS usage: char_string
type: character string
access: modify
mechanism: by descriptor
Identifies the key whose value you are listing. The key-name
argument is the address of a descriptor pointing to the key name.
if-state
VMS usage: char_string
type: character string
access: write only
mechanism: by descriptor
Receives the state name which qualifies the next definition in the
key table. The if-state argument is the address of a descriptor
pointing to the storage into which the state name is written.
attributes
VMS usage: mask_longword
type: longword (unsigned)
access: write only
mechanism: by reference
Attributes of this key definition. The attributes argument is the
address of an unsigned longword into which is written the key
attributes.
equivalence-string
VMS usage: char_string
type: character string
access: write only
mechanism: by descriptor
The character string into which is written the equivalence string
for the next key definition. The equivalence-string argument is the
address of a descriptor pointing to the storage into which the
equivalence string is written.
state-string
VMS usage: char_string
type: character string
access: write only
mechanism: by descriptor
A string into which is written the new state name, if any, which is
set by the next key definition. The state-string argument is the
address of a descriptor pointing to the storage into which the state
name is written. If this key definition sets a state, the
attributes flag SMG$V_KEY_SETSTATE is set.
SMG$LIST_PASTING_ORDER
The Return Pasting Information routine returns the identifiers of
the virtual displays pasted to a specified pasteboard. Optionally,
the pasteboard row 1 and column 1 (upper left corner) of the virtual
display are also returned.
Format:
SMG$LIST_PASTING_ORDER pasteboard-id ,context
,display-id [,pasteboard-row] [,pasteboard-column]
Arguments:
pasteboard-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Identifier of the pasteboard on which the virtual display is to be
pasted. The pasteboard-id argument is the address of an unsigned
longword containing the identifier of this pasteboard.
context
VMS usage: identifier
type: longword (unsigned)
access: modify
mechanism: by reference
Context to search. The context argument is the address of an
unsigned longword containing this context. On the initial call, you
should set context to zero. SMG$LIST_PASTING_ORDER updates the
value of context. The updated value should then be passed on
subsequent calls to obtain the next pasted display.
display-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Identifier of the virtual display that is pasted. The display-id
argument is the address of an unsigned longword containing the
identifier of this virtual display.
pasteboard-row
VMS usage: longword_signed
type: longword (signed)
access: write only
mechanism: by reference
Row of the pasteboard that contains row 1 of the specified virtual
display. The optional pasteboard-row argument is the address of a
signed longword containing the row number of the pasteboard row that
contains the first row of the virtual display.
pasteboard-column
VMS usage: longword_signed
type: longword (signed)
access: write only
mechanism: by reference
Column of the pasteboard that contains column 1 of the specified
virtual display. The optional pasteboard-column argument is the
address of a signed longword containing the column number of the
pasteboard column that contains the first column of the virtual
display.
SMG$LOAD_KEY_DEFS
The Load Key Definitions routine loads a file of key definitions
(DEFINE/KEY commands) into a specified key table.
Format:
SMG$LOAD_KEY_DEFS key-table-id ,filespec [,default-filespec]
[,flags]
Arguments:
key-table-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the key table into which you are loading key definitions.
The key-table-id argument is the address of an unsigned longword
that contains the key table identifier.
filespec
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
String containing the file specification for the file of DEFINE/KEY
commands. The filespec argument is the address of a descriptor
pointing to the file specification.
default-filespec
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
String containing the default file specification for the file of
DEFINE/KEY commands. The default-filespec argument is the address
of a descriptor pointing to the default file specification. If
omitted, the null string is used.
flags
VMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies whether filespec is to be treated as a logical name. The
flags argument is the address of an unsigned longword that contains
the flag. If set, flags specifies that filespec should be
translated, but if this is not possible, that the null string be
used.
SMG$LOAD_VIRTUAL_DISPLAY
The Load a Virtual Display from a File routine creates a new virtual
display and loads it with a virtual display saved with
SMG$SAVE_VIRTUAL_DISPLAY.
Format:
SMG$LOAD_VIRTUAL_DISPLAY display-id [,file-spec]
Arguments:
display-id
VMS usage: identifier
type: longword (unsigned)
access: write only
mechanism: by reference
Identifier of the new virtual display to be loaded with the saved
virtual display. The display-id argument is the address of an
unsigned longword into which is written the new display identifier.
file-spec
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
String containing the file specification of the file in which the
specified virtual display is saved. The file-spec argument is a
character string containing the file specification.
SMG$MOVE_TEXT
The Move Text from One Virtual Display to Another routine moves a
rectangle of text from one virtual display to another virtual
display. Given two points in opposite corners of the rectangle,
SMG$MOVE_TEXT determines the desired width and height.
Format:
SMG$MOVE_TEXT display-id ,top-left-row ,top-left-column
,bottom-right-row ,bottom-right-column ,display-id2
[,top-left-row2] [,top-left-column2] [,flags]
Arguments:
display-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the virtual display whose text is to be moved. The
display-id argument is the address of an unsigned longword that
contains the display identifier.
top-left-row
VMS usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
Top left row of the rectangle of text you want to move. The
top-left-row argument is the address of an unsigned longword
containing the row number.
top-left-column
VMS usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
Top left column of the rectangle of text you want to move. The
top-left-column argument is the address of an unsigned longword
containing the column number.
bottom-right-row
VMS usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
Bottom right row of the rectangle of text you want to move. The
bottom-right-row argument is the address of an unsigned longword
containing the row number.
bottom-right-column
VMS usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
Bottom right column of the rectangle of text you want to move. The
bottom-right-column argument is the address of an unsigned longword
containing the column number.
display-id2
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the virtual display to which the text is to be moved. The
display-id argument is the address of an unsigned longword that
contains the display identifier.
top-left-row2
VMS usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
Top left row of the rectangle that is the destination of the text
you want to move. The optional top-left-row2 argument is the
address of an unsigned longword containing the row number. If you
do not specify a value for top-left-row2, the text is moved to the
current virtual cursor row.
top-left-column2
VMS usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
Top left column of the rectangle that is the destination of the text
you want to move. The optional top-left-column2 argument is the
address of an unsigned longword containing the column number. If
you do not specify a value for top-left-column2, the text is moved
to the current virtual cursor column.
flags
VMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Bit mask that specifies optional behavior. The flags argument is
the address of a longword bit mask specifying these options. Valid
values are as follows:
SMG$M_TEXT_SAVE Does not erase the text after moving.
SMG$M_TEXT_ONLY Moves the text but not the attributes.
SMG$MOVE_VIRTUAL_DISPLAY
The Move Virtual Display routine relocates a virtual display on a
pasteboard and preserves the pasting order.
Format:
SMG$MOVE_VIRTUAL_DISPLAY display-id ,pasteboard-id
,pasteboard-row ,pasteboard-column [,top-display-id]
Arguments:
display-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the virtual display to be moved. The display-id argument
is the address of an unsigned longword that contains the display
identifier.
pasteboard-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the pasteboard on which the movement is to take place.
The pasteboard-id argument is the address of an unsigned longword
that contains the pasteboard identifier.
pasteboard-row
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Specifies the row of the pasteboard that is to contain row 1 of the
specified virtual display. The pasteboard-row argument is the
address of a signed longword integer that contains the row number.
pasteboard-column
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Specifies the column of the pasteboard that is to contain column 1
of the specified virtual display. The pasteboard-column argument is
the address of a signed longword integer that contains the column
number.
top-display-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Identifier of the virtual display under which the unpasted
display-id will be pasted. The top-display-id argument is the
address of an unsigned longword containing the specified virtual
display identifier. Note that the use of the top-display-id
argument is only valid when the virtual display specified by
display-id is not currently pasted and the virtual display specified
by top-display-id is pasted.
SMG$NAME_TO_KEYCODE
The Translate a Key Name into a Key Code routine translates the key
name of a key on the keyboard into its associated key code.
Format:
SMG$NAME_TO_KEYCODE key-name ,key-code
Arguments:
key-name
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
String containing the name of the key to be translated into a key
code. The key-name argument is the address of a descriptor pointing
to the character string containing the key name. The key-name
argument is simply the name of the key, for example COMMA, PERIOD,
KP4, and so forth.
key-code
VMS usage: word_signed
type: word (signed)
access: write only
mechanism: by reference
Specifies the key code into which key-name is to be translated. The
key-code argument is the address of a signed word that contains the
key code.
SMG$PASTE_VIRTUAL_DISPLAY
The Paste Virtual Display routine pastes a virtual display to a
pasteboard.
Format:
SMG$PASTE_VIRTUAL_DISPLAY display-id ,pasteboard-id
,pasteboard-row ,pasteboard-column [,top-display-id]
Arguments:
display-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the virtual display to be pasted. The display-id argument
is the address of an unsigned longword that contains the display
identifier.
pasteboard-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the pasteboard to which the display is to be pasted. The
pasteboard-id argument is the address of an unsigned longword that
contains the pasteboard identifier.
pasteboard-row
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Specifies the row of the pasteboard that is to contain row 1 of the
specified virtual display. The pasteboard-row argument is the
address of a signed longword integer that contains the row number.
pasteboard-column
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Specifies the column of the pasteboard that is to contain column 1
of the specified virtual display. The pasteboard-column argument is
the address of a signed longword integer that contains the column
number.
top-display-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Identifier of the virtual display under which to paste display-id.
The optional top-display-id argument is the address of an unsigned
longword containing this identifier. Note that the virtual display
specified by top-display-id must already be pasted.
SMG$POP_VIRTUAL_DISPLAY
The Delete a Series of Virtual Displays routine deletes a specified
virtual display and all displays that were pasted on the specified
pasteboard after the specified virtual display.
Format:
SMG$POP_VIRTUAL_DISPLAY display-id ,pasteboard-id
Arguments:
display-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the lowest (first) virtual display to be deleted. The
display-id argument is the address of an unsigned longword that
contains the display identifier. All displays that are higher in
the pasting order (that is, all displays that were pasted after the
specified display) are deleted as well.
pasteboard-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the pasteboard on which the display deletions take place.
The pasteboard-id argument is the address of an unsigned longword
that contains the pasteboard identifier.
SMG$PRINT_PASTEBOARD
The Print Pasteboard Using a Print Queue routine prints the contents
of the specified pasteboard on a line printer.
Format:
SMG$PRINT_PASTEBOARD pasteboard-id [,queue-name] [,copies]
Arguments:
pasteboard-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Identifier of the pasteboard to be printed. The pasteboard-id
argument is the address of an unsigned longword containing this
identifier.
queue-name
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
Optional queue name. The queue-name argument is the address of a
descriptor pointing to the queue name in which to enter the file.
The default is SYS$PRINT.
copies
VMS usage: longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Optional number of copies to print. The copies argument is the
address of a signed longword containing this number. The default
and minimum is one copy.
SMG$PUT_CHARS
The Write Characters to a Virtual Display routine overwrites
characters in a virtual display with the text you specify.
Format:
SMG$PUT_CHARS display-id ,text [,start-row]
[,start-column] [,flags] [,rendition-set]
[,rendition-complement] [,character-set]
Arguments:
display-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the virtual display affected. The display-id argument is
the address of an unsigned longword that contains the display
identifier.
text
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
Characters to be written to the virtual display. The text argument
is the address of a descriptor pointing to the character string.
start-row
VMS usage: longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Specifies the row at which output begins. If start-row is omitted,
output begins on the current row. The start-row argument is the
address of a signed longword integer that contains the row number.
start-column
VMS usage: longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Specifies the column at which output begins. If start-column is
omitted, output begins on the current column. The start-column
argument is the address of a signed longword integer that contains
the column number.
flags
VMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the action to take before the specified text is output.
The flags argument is the address of an unsigned longword that
contains the flag. Flags accepts the following values:
SMG$M_ERASE_TO_EOL Erase remaining part of line
SMG$M_ERASE_LINE Erase entire line
0 Do not erase line (the default)
rendition-set
VMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Optional attribute specifier. The rendition-set argument is the
address of a longword bit mask. Each bit attribute in this argument
causes the corresponding attribute to be set in the display.
rendition-complement
VMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Optional attribute complement specifier. The rendition-complement
argument is the address of an unsigned longword that contains a
video attributes mask. Each bit attribute in this argument causes
the corresponding attribute to be set in the display. All of the
attributes that can be specified with the rendition-set argument can
be complemented with the rendition-complement argument.
character-set
VMS usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the default character set for all text in this virtual
display. The character-set argument is the address of an unsigned
longword that contains the character set code. Valid values are
SMG$C_ASCII (the default), and SMG$C_SPEC_GRAPHICS.
SMG$PUT_CHARS_HIGHWIDE
The Write Double-Height Double-Width Characters routine writes
double-height, double-width characters to a virtual display.
Format:
SMG$PUT_CHARS_HIGHWIDE display-id ,text [,start-row]
[,start-column] [,rendition-set]
[,rendition-complement] [,character-set]
Arguments:
display-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the virtual display affected. The display-id argument is
the address of an unsigned longword that contains the display
identifier.
text
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
Characters to be written to the virtual display. The text argument
is the address of a descriptor pointing to the text.
start-row
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Specifies the line at which output begins. The start-row argument
is the address of a signed longword integer that contains the line
number. If start-row is omitted or if it is equal to zero, output
begins on the current line.
start-column
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Specifies the column at which output begins. The start-column
argument is the address of a signed longword integer that contains
the column number. If start-column is omitted or if it is equal to
zero, output begins on the current column.
rendition-set
VMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Mask which denotes video attributes for the drawn line. The
rendition-set argument is the address of an unsigned longword that
contains a video attributes mask. Each bit attribute in this
argument causes the corresponding attribute to be set in the
display.
rendition-complement
VMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Mask which denotes video attributes for the line drawn. The
rendition-complement argument is the address of an unsigned longword
that contains a video attributes mask.
character-set
VMS usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the default character set for all text in this virtual
display. The character-set argument is the address of an unsigned
longword that contains the character set code. At this time, the
only valid value is SMG$C_ASCII, which is also the default.
SMG$PUT_CHARS_MULTI
The Put Text with Multiple Renditions routine writes text with
multiple renditions to the virtual display.
Format:
SMG$PUT_CHARS_MULTI display-id ,text [,line-number]
[,column-number] [,flags] [,rendition-set]
[,rendition-complement] [,character-set]
Arguments:
display-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Identifier of the virtual display to be affected. The display-id
argument is the address of an unsigned longword that contains this
identifier.
text
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
Text to be output. The text argument is the address of a descriptor
pointing to the output string.
line-number
VMS usage: longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Optional line number at which to start output. The line-number
argument is the address of a signed longword containing this number.
If omitted, the current line number is used.
column-number
VMS usage: longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Optional column number at which to start output. The column-number
argument is the address of a signed longword containing this number.
If omitted, the current column number is used.
flags
VMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the action to take before the specified text is output.
The flags argument is the address of an unsigned longword that
contains the flag. Flags accepts the following values:
SMG$M_ERASE_TO_EOL Erase remaining part of line
SMG$M_ERASE_LINE Erase entire line
0 Do not erase line (the default)
rendition-set
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
Bit mask string that controls the video attributes. The
rendition-set argument is the address of a descriptor pointing to
this bit mask string. Each one-bit attribute causes the
corresponding attribute to be set for the corresponding byte in the
text string in the display. The following attributes can be
specified for each byte using the rendition-set argument:
SMG$M_BLINK Displays characters blinking.
SMG$M_BOLD Displays characters in
higher-than-normal intensity.
SMG$M_REVERSE Displays characters in reverse video,
that is, using the opposite default
rendition of the virtual display.
SMG$M_UNDERLINE Displays characters underlined.
SMG$M_INVISIBLE Makes characters in the virtual display
invisible.
SMG$M_USER1 through SMG$M_USER8 Displays user-defined
attributes.
rendition-complement
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
Optional bit mask string that controls the video attributes. The
rendition-complement argument is the address of a descriptor
pointing to this bit mask string. Each one-bit attribute causes the
corresponding attribute to be complemented for the corresponding
byte in the text string in the display.
character-set
VMS usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
Optional default character set for the text in the virtual display.
The character-set argument is the address of an unsigned longword
that contains the character set code. Valid values are SMG$C_ASCII
(the default), and SMG$C_SPEC_GRAPHICS.
SMG$PUT_CHARS_WIDE
The Write Wide Characters routine writes double-width characters to
a virtual display.
Format:
SMG$PUT_CHARS_WIDE display-id ,text [,start-row] [,start-column]
[,rendition-set] [,rendition-complement]
[,character-set]
Arguments:
display-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the virtual display affected. The display-id argument is
the address of an unsigned longword that contains the display
identifier.
text
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
Characters to be written to the virtual display. The text argument
is the address of a descriptor pointing to the text.
start-row
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Specifies the line at which output begins. If start-row is omitted,
output begins on the current line. The start-row argument is the
address of a signed longword integer that contains the line number.
start-column
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Specifies the column at which output begins. If start-column is
omitted, output begins on the current column. The start-column
argument is the address of a signed longword integer that contains
the column number.
rendition-set
VMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Mask which denotes video attributes for the drawn line. The
rendition-set argument is the address of an unsigned longword that
contains a video attributes mask. Each bit attribute in this
argument causes the corresponding attribute to be set in the
display.
rendition-complement
VMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Mask which denotes video attributes for the line drawn. The
rendition-complement argument is the address of an unsigned longword
that contains a video attributes mask. Each bit attribute in this
argument causes the corresponding attribute to be set in the
display. Video attributes which can be manipulated in this manner
are the same as those for the rendition-set argument.
character-set
VMS usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the default character set for all text in this virtual
display. The character-set argument is the address of an unsigned
longword that contains the character set code. At this time, the
only valid value is SMG$C_ASCII, which is also the default.
SMG$PUT_HELP_TEXT
The Output HELP Text to the Display routine retrieves and outputs
the HELP text for the specified topic in the virtual display
provided.
Format:
SMG$PUT_HELP_TEXT display-id [,keyboard-id] [,HELP-topic]
[,HELP-library] [,rendition-set] [,rendition-complement]
Arguments:
display-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Display identifier of the virtual display to which the HELP text is
written. The display-id argument is the address of an unsigned
longword that contains this virtual display identifier. Note that
this display must be pasted and cannot be occluded or batched.
keyboard-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Optional keyboard identifier of the virtual keyboard used for input.
The keyboard-id argument is the address of an unsigned longword that
contains this virtual keyboard identifier. If the keyboard-id
parameter is not specified, prompting is disabled.
HELP-topic
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
Optional HELP topic. The HELP-topic argument is the address of a
descriptor pointing to the HELP topic string.
HELP-library
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
Optional HELP library name. The HELP-library argument is the
address of a descriptor pointing to the HELP library name. The
default is SYS$HELP:HELPLIB.HLB.
rendition-set
VMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Optional bit mask that denotes video attributes for the virtual
display. The rendition-set argument is the address of an unsigned
longword that contains a video attributes mask. Each one-bit
attribute in this argument causes the corresponding attribute to be
set in the display.
rendition-complement
VMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Optional bit mask that denotes video attributes for the virtual
display. The rendition-complement argument is the address of an
unsigned longword that contains a video attributes mask.
SMG$PUT_LINE
The Write Line to Virtual Display routine writes a line of text to a
virtual display.
Format:
SMG$PUT_LINE display-id ,text [,line-advance] [,rendition-set]
[,rendition-complement] [,flags] [,character-set]
[,direction]
Arguments:
display-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the virtual display affected. The display-id argument is
the address of an unsigned longword that contains the display
identifier.
text
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
The characters to be written to the virtual display. The text
argument is the address of a descriptor pointing to the text.
line-advance
VMS usage: longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Specifies the number of lines to advance after output. The
line-advance argument is the address of a signed longword integer
that contains the number of lines to advance. The default is 1.
rendition-set
VMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
A mask that denotes video attributes for the drawn line. The
rendition-set argument is the address of an unsigned longword that
contains a video attributes mask. Each bit attribute in this
argument causes the corresponding attribute to be set in the
display.
rendition-complement
VMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
A mask that denotes video attributes for the line drawn. The
rendition-complement argument is the address of an unsigned longword
that contains a video attributes mask. Each bit attribute in this
argument causes the corresponding attribute to be set in the
display. Video attributes that can be manipulated in this manner
are the same as those for the rendition-set argument.
flags
VMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the action to take if the text does not fit on the line.
The flags argument is the address of an unsigned longword that
contains the flag. The flags argument accepts the following values:
SMG$M_WRAP_CHAR Wraps at last character on line
SMG$M_WRAP_WORD Wraps at last space on line
character-set
VMS usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the default character set for all text in this virtual
display. The character-set argument is the address of an unsigned
longword that contains the character set code. Valid values are
SMG$C_ASCII (the default), and SMG$C_SPEC_GRAPHICS.
direction
VMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the direction to scroll, if scrolling is necessary. The
direction argument is the address of a longword bit mask that
contains the direction code. Valid values are SMG$M_UP and
SMG$M_DOWN. SMG$M_UP is the default.
SMG$PUT_LINE_HIGHWIDE
The Write Double-High and Double-Width Line routine writes lines of
text with double-high and double-wide characters.
Format:
SMG$PUT_LINE_HIGHWIDE display-id ,text [,line-advance]
[,rendition-set] [,rendition-complement] [,flags]
[,character-set]
Arguments:
display-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Display identifier. The display-id argument is the address of an
unsigned longword that contains the display identifier of the
virtual display.
text
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
Text to be output. The text argument is the address of the
descriptor pointing to the output string.
line-advance
VMS usage: longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Number of lines to advance. The line-advance argument is the
address of a signed longword that contains the number of lines to
advance after the output. This argument is optional.
rendition-set
VMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
A mask that denotes video attributes for the drawn line. The
rendition-set argument is the address of an unsigned longword that
contains attribute information. Each one-bit attribute in this
argument causes the corresponding attribute to be set in the
display.
rendition-complement
VMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
A mask that denotes video attributes for the line drawn. The
rendition-complement argument is the address of an unsigned longword
that contains attribute information. Each one-bit attribute in this
argument causes the corresponding attribute to be complemented in
the display. Video attributes that can be manipulated in this
manner are the same as those for the rendition-set argument.
flags
VMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the action to take if the text does not fit on the line.
The flags argument is the address of an unsigned longword that
contains the flag. The flags argument accepts the following values:
SMG$M_WRAP_CHAR Wrap at last character on line
SMG$M_WRAP_WORD Wrap at last space on line
character-set
VMS usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the default character set for all text in this virtual
display. The character-set argument is the address of an unsigned
longword that contains the character-set code. Valid values are
SMG$C_ASCII (the default), and SMG$C_SPEC_GRAPHICS.
SMG$PUT_LINE_MULTI
The Put Text with Multiple Renditions to Display in Line Mode
routine writes lines with multiple renditions to the virtual
display, optionally followed by cursor movement sequences.
Format:
SMG$PUT_LINE_MULTI display-id ,text ,rendition-set
[,rendition-complement] [,line-advance] [,flags]
[,direction] [,character-set]
Arguments:
display-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Identifier of the virtual display to be affected. The display-id
argument is the address of an unsigned longword that contains this
identifier.
text
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
Text to be output. The text argument is the address of a descriptor
pointing to the output string.
rendition-set
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
Bit mask string that controls the video attributes. The
rendition-set argument is the address of a descriptor pointing to
this bit mask string. Each one-bit attribute causes the
corresponding attribute to be set for the corresponding byte in the
text string in the display. The following attributes can be
specified for each byte using the rendition-set argument:
SMG$M_BLINK Displays characters blinking.
SMG$M_BOLD Displays characters in
higher-than-normal intensity.
SMG$M_REVERSE Displays characters in reverse video,
that is, using the opposite default
rendition of the virtual display.
SMG$M_UNDERLINE Displays characters underlined.
SMG$M_INVISIBLE Makes characters in the virtual display
invisible.
SMG$M_USER1 through SMG$M_USER8 Displays user-defined
attributes.
rendition-complement
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
Optional bit mask string that controls the video attributes. The
rendition-complement argument is the address of a descriptor
pointing to this bit mask string. Each one-bit attribute causes the
corresponding attribute to be complemented for the corresponding
byte in the text string in the display.
line-advance
VMS usage: longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Optional number of lines to advance after output. The line-advance
argument is the address of a signed longword containing this number.
flags
VMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the action to take if the text does not fit on the line.
The flags argument is the address of an unsigned longword that
contains the flag. The flags argument accepts the following values:
SMG$M_WRAP_CHAR Wrap at last character on line
SMG$M_WRAP_WORD Wrap at last space on line
direction
VMS usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
Optional direction specifier. The direction argument is the address
of an unsigned longword that contains the direction code specifying
the scrolling direction, if scrolling is necessary. Valid values
for direction are as follows:
o SMG$M_UP
o SMG$M_DOWN
character-set
VMS usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
Optional default character set for the text in the virtual display.
The character-set argument is the address of an unsigned longword
that contains the character set code. Valid values are SMG$C_ASCII
(the default), and SMG$C_SPEC_GRAPHICS.
SMG$PUT_LINE_WIDE
The Write Double-Width Line routine writes a line of double-width
text to a virtual display.
Format:
SMG$PUT_LINE_WIDE display-id ,text [,line-advance]
[,rendition-set] [,rendition-complement]
[,flags] [,character-set]
Arguments:
display-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the virtual display affected. The display-id argument is
the address of an unsigned longword that contains the display
identifier.
text
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
Characters to be written to the virtual display. The text argument
is the address of a descriptor pointing to the text.
line-advance
VMS usage: longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Specifies the number of lines to advance after output. The
line-advance argument is the address of a signed longword integer
that contains the number of lines to advance.
rendition-set
VMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Mask that denotes video attributes for the drawn line. The
rendition-set argument is the address of an unsigned longword that
contains a video attributes mask. Each bit attribute in this
argument causes the corresponding attribute to be set in the
display.
rendition-complement
VMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Mask that denotes video attributes for the line drawn. The
rendition-complement argument is the address of an unsigned longword
that contains a video attributes mask.
flags
VMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the action to take if the text does not fit on the line.
The flags argument is the address of an unsigned longword that
contains the flag. The flags argument accepts the following values:
SMG$M_WRAP_CHAR Wrap at last character on line
SMG$M_WRAP_WORD Wrap at last space on line
character-set
VMS usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the default character set for all text in this virtual
display. The character-set argument is the address of an unsigned
longword that contains the character set code. Valid values are
SMG$C_ASCII (the default), and SMG$C_SPEC_GRAPHICS.
SMG$PUT_PASTEBOARD
The Output Pasteboard via Routine routine accesses the contents of a
pasteboard.
Format:
SMG$PUT_PASTEBOARD pasteboard-id ,action-routine
,user-argument ,flags
Arguments:
pasteboard-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Pasteboard identifier. The pasteboard-id argument is the address of
an unsigned longword containing the pasteboard identifier.
action-routine
VMS usage: procedure
type: procedure entry mask
access: read only
mechanism: by value
Pasteboard routine. The action-routine argument is the address of
the routine to be called.
user-argument
VMS usage: user_arg
type: unspecified
access: read only
mechanism: by reference
Pasteboard argument. The user-argument argument is a
user-specified argument to be passed to the action routine. If
omitted, a 0 will be passed as the user argument.
flags
VMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Bit mask that specifies optional behavior. If 1, then the first
line passed to the action routine will be a form feed. If not
specified, then no form-feed line will be sent.
SMG$PUT_STATUS_LINE
The Output Line of Text to Hardware Status Line routine outputs a
line of text to the hardware status line.
Format:
SMG$PUT_STATUS_LINE pasteboard-id ,text
Arguments:
pasteboard-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the pasteboard containing the hardware status line. The
pasteboard-id argument is the address of an unsigned longword that
contains the pasteboard identifier.
text
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
The characters to be written to the hardware status line. The text
argument is the address of a descriptor pointing to the text.
SMG$READ_COMPOSED_LINE
The Read Composed Line routine reads a line of input composed of
normal keystrokes and equivalence strings.
Format:
SMG$READ_COMPOSED_LINE keyboard-id ,key-table-id
,resultant-string [,prompt-string] [,resultant-length]
[,display-id] [,flags] [,initial-string] [,timeout]
[,rendition-set] [,rendition-complement]
[,word-integer-terminator-code]
Arguments:
keyboard-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the virtual keyboard from which input is to be read. The
keyboard-id argument is the address of an unsigned longword that
contains the keyboard identifier.
key-table-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the key table to be used for translating keystrokes. The
key-table-id argument is the address of an unsigned longword that
contains the key table identifier.
resultant-string
VMS usage: char_string
type: character string
access: write only
mechanism: by descriptor
String into which SMG$READ_COMPOSED_LINE writes the complete
composed line. The resultant-string argument is the address of a
descriptor pointing to the storage in which the composed line is
written.
prompt-string
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
String used to prompt for the read operation. The prompt-string
argument is the address of a descriptor pointing to the prompt
string.
resultant-length
VMS usage: word_unsigned
type: word (unsigned)
access: write only
mechanism: by reference
Receives the number of characters read or the maximum length of
resultant-string, whichever is less. The resultant-length argument
is the address of an unsigned longword into which
SMG$READ_COMPOSED_LINE writes the number of characters read.
display-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Display identifier. The display-id argument is the address of an
unsigned longword that contains the display identifier. This
argument is optional only if you are not using the Screen Management
Facility's output routines.
flags
VMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Function keys. The flags argument is the address of an unsigned
longword. If flags equals 1, then the function keys can be used and
line editing is disabled. If flags equals zero, line editing is
enabled and the function keys cannot be used.
initial-string
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
Optional string that contains the initial characters of the field.
The initial-string argument is the address of a descriptor pointing
to the string.
timeout
VMS usage: longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Optional timeout count. The timeout argument is the address of a
signed longword containing the timeout count. If the timeout
argument is specified, all characters entered before the timeout are
returned in the buffer. If the timeout argument is omitted,
characters are returned in the buffer until a terminator is
encountered.
rendition-set
VMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Optional attribute specifier. The rendition-set argument is the
address of a longword bit mask in which each 1-bit attribute causes
the corresponding attribute to be set in the display. The following
attributes can be specified by the rendition-set argument:
SMG$M_BLINK Displays characters blinking.
SMG$M_BOLD Displays characters in higher-than-normal
intensity (bolded).
SMG$M_REVERSE Displays characters in reverse video ---
that is, using the opposite default
rendition of the virtual display.
SMG$M_UNDERLINE Displays characters underlined.
rendition-complement
VMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Optional attribute complement specifier. The rendition-complement
argument is the address of a longword bit mask rendition-set in
which each 1-bit attribute causes the corresponding attribute to be
complemented in the display. All of the attributes that can be
specified with the rendition-set argument can be complemented with
the rendition-complement argument. The display-id argument must be
specified when the rendition-complement argument is used.
word-integer-terminator-code
VMS usage: word_unsigned
type: word (unsigned)
access: write only
mechanism: by reference
Key terminator code. The word-integer-terminator-code argument is
an unsigned word into which is written a code indicating what
character or key terminated the read. Key terminator codes are of
the form SMG$K_TRM_keyname.
SMG$READ_FROM_DISPLAY
The Read Text from Display routine reads a line of text from a
virtual display.
Format:
SMG$READ_FROM_DISPLAY display-id ,resultant-string
[,terminator-string] [,start-row]
Arguments:
display-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the virtual display from which text is read. The
display-id argument is the address of an unsigned longword that
contains the display identifier.
resultant-string
VMS usage: char_string
type: character string
access: write only
mechanism: by descriptor
String into which SMG$READ_FROM_DISPLAY writes the information read
from the virtual display. The resultant-string argument is the
address of a descriptor pointing to the storage into which the
string is written.
terminator-string
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
String containing a terminator or terminators that end the backward
search, thus determining the starting position of the returned
string. The terminator-string argument is the address of a
descriptor pointing to the string of terminators. If omitted, no
back searching is performed; the returned string starts with the
character at the current cursor position.
start-row
VMS usage: longword_signed
type: longword (signed)
access: read only
mechanism: by reference
The start-row argument is the address of a signed longword that
contains the row of the display-id to read from. This is an
optional argument.
SMG$READ_KEYSTROKE
The Read a Single Character routine reads a keystroke and returns
that keystroke's terminator code.
Format:
SMG$READ_KEYSTROKE keyboard-id ,word-integer-terminator-code
[,prompt-string] [,timeout] [,display-id]
[,rendition-set] [,rendition-complement]
Arguments:
keyboard-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Keyboard identifier. The keyboard-id argument is an unsigned
longword containing the identification of the virtual keyboard from
which to read. A virtual keyboard is created by calling the
SMG$CREATE_VIRTUAL_KEYBOARD routine.
word-integer-terminator-code
VMS usage: word_unsigned
type: word (unsigned)
access: write only
mechanism: by reference
Key terminator code. The word-integer-terminator-code argument is
an unsigned word into which is written a code indicating what
character or key terminated the read. Key terminator codes are of
the form SMG$K_TRM_keyname.
prompt-string
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
Prompt string. The prompt-string argument is an optional string
that is used as the prompt for the read operation.
timeout
VMS usage: longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Timeout count. The timeout argument is optional. If specified, any
character typed before the timeout is returned in the buffer.
display-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Display identifier. The optional display-id argument is the address
of an unsigned longword that contains the identifier of the virtual
display in which the read is to be performed. If the optional
prompt-string argument is specified while there are multiple virtual
displays pasted, the display-id argument is required to determine in
which virtual display the prompt string will be written. If the
prompt-string argument is not specified, then do not specify the
display-id argument.
rendition-set
VMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Attribute specifier. The optional rendition-set argument is the
address of a longword bit mask in which each 1-bit attribute causes
the corresponding attribute to be set in the display. The following
attributes can be specified by the rendition-set argument:
SMG$M_BLINK Displays characters blinking.
SMG$M_BOLD Displays characters in higher-than-normal
intensity (bolded).
SMG$M_REVERSE Displays characters in reverse video ---
that is, using the opposite default
rendition of the virtual display.
SMG$M_UNDERLINE Displays characters underlined.
rendition-complement
VMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Attribute complement specifier. The optional rendition-complement
argument is the address of a longword bit mask in which each 1-bit
attribute causes the corresponding attribute to be complemented in
the display. All of the attributes that can be specified with the
rendition-set argument can be complemented with the
rendition-complement argument. The display-id argument must be
specified when using the rendition-complement argument.
SMG$READ_STRING
The Read String routine reads a string from a virtual keyboard.
Format:
SMG$READ_STRING keyboard-id ,resultant-string [,prompt-string]
[,maximum-length] [,modifiers] [,timeout]
[,placeholder-arg] [,resultant-length]
[,word-integer-terminator-code] [,display-id]
[,initial-string] [,rendition-set]
[,rendition-complement] [,terminator-string]
Arguments:
keyboard-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the virtual keyboard from which input is to be read. The
keyboard-id argument is the address of an unsigned longword that
contains the keyboard identifier.
resultant-string
VMS usage: char_string
type: character string
access: write only
mechanism: by descriptor
String into which the input line is written. The resultant-string
argument is the address of a descriptor pointing to the storage into
which the text is written.
prompt-string
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
String used to prompt for the read operation. The prompt argument
is the address of a descriptor pointing to the prompt string.
maximum-length
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Specifies the maximum number of characters to be read. The
maximum-length argument is the address of a signed longword integer
that contains the maximum number of characters to be read. The
maximum valid value for this argument is 512. If omitted, 512 is
the default.
modifiers
VMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Bit mask that specifies optional behavior. The modifiers argument
is the address of an unsigned longword that contains the bit mask.
timeout
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Specifies the number of seconds allowed between the time the prompt
is issued and the completion of the input operation. The timeout
argument is the address of a signed longword integer that contains
the number of seconds.
terminator-set
VMS usage: unspecified
type: unspecified
access: read only
mechanism: by descriptor, fixed length
Either a mask that specifies which characters are to be treated as
terminators (short form) or a descriptor pointing to such a mask
(long form). The terminator-set argument is the address of a
descriptor pointing to the mask.
resultant-length
VMS usage: word_unsigned
type: word (unsigned)
access: write only
mechanism: by reference
Receives the number of characters read or the maximum size of
resultant-string, whichever is less. The resultant-length argument
is the address of an unsigned word into which is written the number
of characters or the maximum size.
word-integer-terminator-code
VMS usage: word_unsigned
type: word (unsigned)
access: write only
mechanism: by reference
Key terminator code. The word-integer-terminator-code argument is
an unsigned word into which is written a code indicating what
character or key terminated the read. Key terminator codes are of
the form SMG$K_TRM_keyname.
display-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Display identifier. The display-id argument is the address of an
unsigned longword that contains the display identifier.
initial-string
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
Initial character string. The initial-string argument is the
address of a descriptor pointing to the optional string that
contains the initial characters of the field.
rendition-set
VMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Attribute specifier. The optional rendition-set argument is the
address of a longword bit mask in which each 1-bit attribute causes
the corresponding attribute to be set in the display. The following
attributes can be specified using the rendition-set argument:
SMG$M_BLINK Displays characters blinking.
SMG$M_BOLD Displays characters in higher-than-normal
intensity (bolded).
SMG$M_REVERSE Displays characters in reverse video ---
that is, using the opposite default
rendition of the virtual display.
SMG$M_UNDERLINE Displays characters underlined.
rendition-complement
VMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Attribute complement specifier. The optional rendition-complement
argument is the address of a longword bit mask in which each 1-bit
attribute causes the corresponding attribute to be complemented in
the display. All of the attributes that can be specified with the
rendition-set argument can be complemented with
rendition-complement. The display-id argument must be specified
when using the rendition-complement argument.
terminator-string
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
Characters that terminated I/O. The optional terminator-string
argument is the address of a descriptor pointing to the character
string containing the terminating characters. Terminator-string
returns the actual terminating characters, not the key that was
pressed to terminate the I/O.
SMG$READ_VERIFY
The Read and Verify a String routine reads a sequence of characters
and verifies the sequence.
Format:
SMG$READ_VERIFY keyboard-id ,resultant-string ,initial-string
,picture-string ,fill-character ,clear-character
[,prompt-string] [,modifiers] [,timeout]
[,terminator-set] [,initial-offset]
[,word-integer-terminator-code] [,display-id]
[,alternate-echo-string] [,alternate-display-id]
[,rendition-set][,rendition-complement]
Arguments:
keyboard-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Keyboard identifier. The keyboard-id argument is the address of an
unsigned longword integer containing the identifier of the virtual
keyboard from which to read. The virtual keyboard is created by
calling the SMG$CREATE_VIRTUAL_KEYBOARD routine.
resultant-string
VMS usage: char_string
type: character string
access: write only
mechanism: by descriptor
Output string into which SMG$READ_VERIFY writes the characters that
are read. The resultant-string argument is the address of a
descriptor pointing to this output string.
initial-string
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
Input string that contains the initial characters of the field. The
initial-string argument is the address of a descriptor pointing to
the input string.
picture-string
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
Picture string that contains a picture of what the field is to look
like. The picture-string argument is the address of a descriptor
pointing to the picture string.
fill-character
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
Fill character. The fill-character argument is the address of a
descriptor pointing to the string that contains the character to be
used as a fill character in the initial-string argument.
clear-character
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
Clear character. The clear-character argument is the address of a
descriptor pointing to the string that contains the character to be
displayed for each occurrence of fill-character in initial-string.
prompt-string
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
Prompt string. The prompt-string argument is the address of a
descriptor pointing to the string that SMG$READ_VERIFY uses as the
prompt for the read operation. This is an optional argument.
modifiers
VMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Modifiers. The modifiers argument is a longword bit mask that
specifies optional behavior. The bits defined are the same as for
the $QIO item-list entry TRM$_MODIFIERS. This is an optional
argument.
timeout
VMS usage: longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Timeout count. The timeout argument is optional. If specified, all
the characters typed in before the timeout are returned in the
buffer. If omitted, characters are returned in the buffer until a
terminator is seen.
placeholder-arg
VMS usage: unspecified
type: unspecified
access: read only
mechanism: unspecified
Placeholder argument. The VMS terminal driver ignores this argument
when performing a read-verify.
initial-offset
VMS usage: longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Input string offset. The initial-offset argument is a longword that
contains the number of characters (from the initial-string argument)
to output after the prompt before waiting for input.
word-integer-terminator-code
VMS usage: word_unsigned
type: word (unsigned)
access: write only
mechanism: by reference
Key terminator code. The word-integer-terminator-code argument is
an unsigned word into which SMG$READ_VERIFY writes a code indicating
what character or key terminated the read. Key terminator codes are
of the form SMG$K_TRM_keyname.
display-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Display identifier. The optional display-id argument is the address
of an unsigned longword integer that contains the identifier of the
virtual display in which the read is to be performed. If specified,
SMG$READ_VERIFY begins the read at the current virtual cursor
position in that virtual display. If omitted, the read begins in
the current physical cursor position. Note that the length of the
prompt-string plus the input is limited to the number of visible
columns in the display.
alternate-echo-string
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
Alternate echo string. The alternate-echo-string argument is a
string that is printed after the first character is typed during the
read operation. This is an optional argument.
alternate-display-id
VMS usage: identifier
type: longword (signed)
access: read only
mechanism: by reference
Alternate display identification. The alternate-display-id is a
signed longword integer containing the identification of the virtual
display in which the alternate-echo-string argument is to be
printed. This is an optional argument. If specified, the output
begins at the current virtual cursor position in that virtual
display. If omitted, the value of the display-id argument is used
as the default. If display-id is not specified, the output begins
in the current physical cursor position.
rendition-set
VMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Attribute specifier. The optional rendition-set argument is the
address of a longword bit mask in which each 1-bit attribute causes
the corresponding attribute to be set in the display. The following
attributes can be specified using the rendition-set argument:
SMG$M_BLINK Displays characters blinking.
SMG$M_BOLD Displays characters in higher-than-normal
intensity (bolded).
SMG$M_REVERSE Displays characters in reverse video ---
that is, using the opposite default
rendition of the virtual display.
SMG$M_UNDERLINE Displays characters underlined.
rendition-complement
VMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Attribute complement specifier. The optional rendition-complement
argument is the address of a longword bit mask in which each 1-bit
attribute causes the corresponding attribute to be complemented in
the display. All of the attributes that can be specified with the
rendition-set argument can be complemented with the
rendition-complement argument. The display-id argument must be
specified when using the rendition-complement argument.
SMG$REMOVE_LINE
The Remove a Line From a Virtual Display routine removes a line from
a specified virtual display that was drawn with the SMG$DRAW_LINE or
SMG$DRAW_RECTANGLE routines.
Format:
SMG$REMOVE_LINE display-id ,start-row ,start-column
,end-row ,end-column
Arguments:
display-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the virtual display from which the line is to be removed.
The display-id argument is the address of an unsigned longword that
contains the display identifier.
start-row
VMS usage: longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Specifies the row at which to begin removing the line. The start-row
argument is the address of a signed longword that contains the row
number.
start-column
VMS usage: longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Specifies the column at which to begin removing the line. The
start-column argument is the address of a signed longword that
contains the column number.
end-row
VMS usage: longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Specifies the row at which the line to be removed ends. The end-row
argument is the address of a signed longword that contains the row
number.
end-column
VMS usage: longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Specifies the column at which the line to be removed ends. The
end-column argument is the address of a signed longword that contains
the column number.
SMG$REPAINT_LINE
The Repaint One or More Lines on the Current Screen routine repaints
a series of lines on the current screen.
Format:
SMG$REPAINT_LINE pasteboard-id ,start-row [,number-of-lines]
Arguments:
pasteboard-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Pasteboard identifier. The pasteboard-id argument is the address of
the pasteboard associated with the physical screen to be repainted.
start-row
VMS usage: longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Starting row number. The start-row argument is the address of the
physical row number to start repainting.
number-of-lines
VMS usage: longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Number of contiguous lines to repaint. The number-of-lines argument
is the address of a signed longword containing the number of lines.
This argument is optional. If not specified, the default is 1.
SMG$REPAINT_SCREEN
The Repaint Current Screen routine repaints the current screen after
nonSMG I/O has occurred.
Format:
SMG$REPAINT_SCREEN pasteboard-id
ARGUMENT
pasteboard-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the terminal screen to be repainted. The pasteboard-id
argument is the address of an unsigned longword that contains the
pasteboard identifier.
SMG$REPASTE_VIRTUAL_DISPLAY
The Repaste Virtual Display routine moves a virtual display to a new
position on the pasteboard. The pasting order is not preserved.
Format:
SMG$REPASTE_VIRTUAL_DISPLAY display-id ,pasteboard-id
,pasteboard-row ,pasteboard-column [,top-display-id]
Arguments:
display-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the virtual display to be repasted. The display-id
argument is the address of an unsigned longword that contains the
display identifier.
pasteboard-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the pasteboard on which the display is repasted. The
pasteboard-id argument is the address of an unsigned longword that
contains the pasteboard identifier.
pasteboard-row
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Specifies the pasteboard row that is to contain row 1 of the
specified virtual display. The pasteboard-row argument is the
address of a signed longword integer that contains the pasteboard
row.
pasteboard-column
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Specifies the pasteboard column that is to contain column 1 of the
specified virtual display. The pasteboard-column argument is the
address of a signed longword integer that contains the pasteboard
column.
top-display-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Optional identifier of the virtual display under which display-id
will be pasted. The top-display-id argument is the address of an
unsigned longword containing the identifier of this virtual display.
Note that the virtual display specified by top-display-id must
already be pasted.
SMG$REPLACE_INPUT_LINE
The Replace Input Line routine replaces the specified lines in the
recall buffer with the specified string.
Format:
SMG$REPLACE_INPUT_LINE keyboard-id [,resultant-string]
[,line-count]
Arguments:
keyboard-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Keyboard identifier. The keyboard-id argument is the address of an
unsigned longword containing the identifier of the virtual keyboard
from which to read. The virtual keyboard is created by calling the
SMG$CREATE_VIRTUAL_KEYBOARD routine.
resultant-string
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
String that contains the line to be entered into the recall buffer.
The resultant-string argument is the address of a descriptor
pointing to this string. The default is a null string, which
removes the last line entered.
line-count
VMS usage: byte_unsigned
type: byte (unsigned)
access: read only
mechanism: by reference
Number of lines to be replaced. The line-count argument is the
address of an unsigned byte containing the number of lines to be
replaced with resultant-string. The default value for the
line-count argument is 1 (the last line entered).
SMG$RESTORE_PHYSICAL_SCREEN
The Restore Physical Screen routine rewrites the screen image as it
was at the time the SMG$SAVE_PHYSICAL_SCREEN routine was called.
Format:
SMG$RESTORE_PHYSICAL_SCREEN pasteboard-id ,display-id
Arguments:
pasteboard-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the physical screen to be restored. The pasteboard-id
argument is the address of an unsigned longword that contains the
pasteboard identifier.
display-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the virtual display created by the
SMG$SAVE_PHYSICAL_SCREEN routine. The display-id argument is the
address of an unsigned longword that contains this display
identifier.
SMG$RETURN_CURSOR_POS
The Return Cursor Position routine returns the current virtual
cursor position in a specified virtual display.
Format:
SMG$RETURN_CURSOR_POS display-id ,start-row ,start-column
Arguments:
display-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the virtual display whose current cursor position you are
requesting. The display-id argument is the address of an unsigned
longword that contains the display identifier. Display-id is
returned by SMG$CREATE_VIRTUAL_DISPLAY.
start-row
VMS usage: longword_signed
type: longword integer (signed)
access: write only
mechanism: by reference
Receives the cursor's current row position within the specified
virtual display. The start-row argument is the address of a
longword into which is written the current row position.
start-column
VMS usage: longword_signed
type: longword integer (signed)
access: write only
mechanism: by reference
Receives the cursor's current column position within the specified
virtual display. The start-column argument is the address of a
longword into which is written the current column position.
SMG$RETURN_INPUT_LINE
The Return Input Line routine returns to the caller the requested
line from the recall buffer. This line is retrieved either by
matching it with a specified string or by specifying the appropriate
line number.
Format:
SMG$RETURN_INPUT_LINE keyboard-id ,resultant-string
[,match-string] [,byte-integer-line-number]
[,resultant-length]
Arguments:
keyboard-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Keyboard identifier. The keyboard-id argument is the address of an
unsigned longword containing the identifier of the virtual keyboard
from which to read. The virtual keyboard is created by calling the
SMG$CREATE_VIRTUAL_KEYBOARD routine.
resultant-string
VMS usage: char_string
type: character string
access: write only
mechanism: by descriptor
String into which is written the complete recalled line. The
resultant-string argument is the address of a descriptor pointing to
this string.
match-string
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
Match string to be used when searching for the line to be recalled.
The optional match-string argument is the address of a descriptor
pointing to this match string. The search begins with the last line
typed.
byte-integer-line-number
VMS usage: byte_unsigned
type: byte (unsigned)
access: read only
mechanism: by reference
Line number to be used when searching for the line to be recalled.
The optional byte-integer-line-number argument is the address of an
unsigned byte containing the number of the line to be recalled. The
last line typed is line number 1.
resultant-length
VMS usage: word_unsigned
type: word (unsigned)
access: write only
mechanism: by reference
Length of the resultant-string string. The optional
resultant-length argument is the address of an unsigned word
containing either the number of characters read or the maximum
length of resultant-string, whichever is less.
SMG$RING_BELL
The Ring the Terminal Bell or Buzzer routine sounds the terminal
bell or buzzer.
Format:
SMG$RING_BELL display-id [,number-of-times]
Arguments:
display-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the virtual display for which the bell or buzzer sounds.
The display-id argument is the address of an unsigned longword that
contains the display identifier.
number-of-times
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Specifies the number of times the bell or buzzer is sounded. The
number-of-times argument is the address of a signed longword integer
that contains the number of times the bell or buzzer is sounded. If
omitted, 1 is used.
SMG$SAVE_PHYSICAL_SCREEN
The Save Physical Screen routine saves the contents of the screen so
that a later call to SMG$RESTORE_PHYSICAL_SCREEN can restore it.
Format:
SMG$SAVE_PHYSICAL_SCREEN pasteboard-id ,display-id
[,desired-start-row] [,desired-end-row]
Arguments:
pasteboard-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the physical screen whose contents are to be saved. The
pasteboard-id argument is the address of an unsigned longword that
contains the pasteboard identifier.
display-id
VMS usage: identifier
type: longword (unsigned)
access: write only
mechanism: by reference
Receives the display id of the display created to contain the
contents of the physical screen. The display-id argument is the
address of an unsigned longword into which the display identifier is
written.
desired-start-row
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Specifies the first row to be saved. The desired-start-row argument
is the address of a signed longword integer that contains the row
number. If omitted, row 1 of the pasteboard is used.
desired-end-row
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Specifies the last row to be saved. The desired-end-row argument is
the address of a signed longword integer that contains the row
number. If omitted, the last row of the pasteboard is used.
SMG$SAVE_VIRTUAL_DISPLAY
The Save the Virtual Display to a File routine saves the contents of
a virtual display and stores it in a file.
Format:
SMG$SAVE_VIRTUAL_DISPLAY display-id [,file-spec]
Arguments:
display-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the virtual display to be saved. The display-id argument
is the address of an unsigned longword that contains the display
identifier.
file-spec
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
String containing the file specification of the file in which the
specified virtual display is saved. The file-spec argument is the
address of a descriptor pointing to a character string containing
the file specification.
SMG$SCROLL_DISPLAY_AREA
The Scroll Display Area routine scrolls a rectangular region of a
virtual display.
Format:
SMG$SCROLL_DISPLAY_AREA display-id [,start-row] [,start-column]
[,height] [,width] [,direction] [,count]
Arguments:
display-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the virtual display in which scrolling takes place. The
display-id argument is the address of an unsigned longword that
contains the display identifier.
start-row
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Specifies the first row of the scrolling region. The start-row
argument is the address of a signed longword integer that contains
the starting row.
start-column
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Specifies the first column of the scrolling region. The
start-column argument is the address of a signed longword integer
that contains the starting column.
height
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Specifies the number of rows in the scrolling region. The height
argument is the address of a signed longword integer that contains
the number of rows.
width
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Specifies the number of columns in the scrolling region. The width
argument is the address of a signed longword integer that contains
the number of columns.
direction
VMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the direction to scroll. The direction argument is the
address of a longword bit mask that contains the direction code.
count
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Specifies the number of lines to scroll. The count argument is the
address of a signed longword integer that contains the number of
units (lines or columns) to scroll. If omitted, one unit is
scrolled.
SMG$SCROLL_VIEWPORT
The Scroll a Display Under a Viewport routine scrolls a virtual
display under its associated viewport.
Format:
SMG$SCROLL_VIEWPORT display-id [,direction] [,count]
Arguments:
display-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Display identifier of the virtual display to be scrolled. The
display-id argument is the address of an unsigned longword
containing this identifier.
direction
VMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Optional direction specifier. The direction argument is the address
of a longword bit mask that contains the direction code specifying
the scrolling direction. The optional count argument can be used to
specify the number of lines to scroll in the specified direction.
Valid values for direction are as follows:
SMG$M_UP Scroll count lines upward.
SMG$M_DOWN Scroll count lines downward.
SMG$M_RIGHT Scroll count columns to the right.
SMG$M_LEFT Scroll count columns to the left.
SMG$M_UP is the default.
count
VMS usage: longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Optional number of rows or columns that will be scrolled. The
default is 1.
SMG$SELECT_FROM_MENU
The Make a Selection from the Menu routine lets you move between the
menu choices using the arrow keys and lets you make a selection by
pressing RETURN.
Format:
SMG$SELECT_FROM_MENU keyboard-id ,display-id
,selected-choice-number [,default-choice-number]
[,flags] [,HELP-library] [,timeout] [,term-code]
[,selected-choice-string] [,rendition-set]
[,rendition-complement]
Arguments:
keyboard-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Identifier of the virtual keyboard from which the terminal user's
responses are read. The keyboard-id argument is the address of an
unsigned longword containing this identifier.
display-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Identifier of the virtual display in which the choices are
displayed. The display-id argument is the address of an unsigned
longword containing this display identifier. This virtual display
must be pasted to a pasteboard and cannot be batched or occluded.
selected-choice-number
VMS usage: word_unsigned
type: word (unsigned)
access: write only
mechanism: by reference
Identification number of the menu item selected. The
selected-choice-number argument is the address of an unsigned word
that receives this number. The selected-choice-number corresponds
to the index of the menu item in the static string array specified
in SMG$CREATE_MENU.
default-choice-number
VMS usage: word_unsigned
type: word (unsigned)
access: read only
mechanism: by reference
Optional identification number of the default menu item. The
default-choice-number argument is the address of an unsigned word
that contains the number of the default menu item. The
default-choice-number corresponds to the index of the default menu
item in the static string array specified in SMG$CREATE_MENU. If
omitted, the default choice will be the last menu item already
selected, or the first item in the menu if no selections have yet
been made.
flags
VMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Optional bit mask indicating optional behavior when a selection is
made. The flags argument is the address of a longword bit mask
containing this flag. Valid values are as follows:
SMG$M_RETURN_IMMED Returns control to the user when
any key other than an arrow key
is entered
SMG$M_REMOVE_ITEM Causes SMG$SELECT_FROM_MENU to only
allow each menu item to be
selected once
HELP-library
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
Optional HELP library to use if the PF2/HELP key is pressed. The
HELP-library argument is the address of a descriptor pointing to
this HELP library name. Note that this argument is ignored if flags
specifies SMG$M_RETURN_IMMED. The default is SYS$HELP:HELPLIB.HLB.
timeout
VMS usage: longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Optional timeout value. The timeout argument is the address of a
signed longword that specifies the number of seconds to wait for a
selection to be made.
term-code
VMS usage: word_unsigned
type: word (unsigned)
access: write only
mechanism: by reference
Optional unsigned word that receives the code indicating which key
terminated the read. The term-code argument is the address of an
unsigned word that receives this terminating key code.
selected-choice-string
VMS usage: char_string
type: character string
access: write only
mechanism: by descriptor
Optional string that receives the text of the menu item selected.
The selected-choice-string is the address of a descriptor pointing
to this string.
rendition-set
VMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Optional attribute specifier. The rendition-set argument is the
address of a longword bit mask in which each one-bit attribute
causes the corresponding attribute to be used when selecting an item
in a menu. The following attributes can be specified by the
rendition-set argument:
SMG$M_BLINK Displays characters blinking.
SMG$M_BOLD Displays characters in higher-than-normal
intensity (bolded).
SMG$M_REVERSE Displays characters in reverse video, that
is, using the opposite default rendition
of the virtual display.
SMG$M_UNDERLINE Displays characters underlined.
SMG$M_INVISIBLE Makes characters in the virtual display
invisible.
SMG$M_USER1 through SMG$M_USER8 Displays user-defined
attributes.
rendition-complement
VMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Optional attribute complement specifier. The rendition-complement
argument is the address of a longword bit mask in which each one-bit
attribute causes the corresponding attribute to be complemented when
selecting an item from the menu. All of the attributes that can be
specified with the rendition-set argument can be complemented with
the rendition-complement argument.
SMG$SET_BROADCAST_TRAPPING
The Enable Broadcast Trapping routine enables the trapping of
broadcast messages.
Format:
SMG$SET_BROADCAST_TRAPPING pasteboard-id [,AST-routine]
[,AST-argument]
Arguments:
pasteboard-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the pasteboard for the terminal to be affected. The
pasteboard-id argument is the address of an unsigned longword that
contains the pasteboard identifier.
AST-routine
VMS usage: ast_procedure
type: procedure entry mask
access: read only
mechanism: by value
The address of an AST routine to be called when a message is
received at the terminal. The AST-routine argument is the address
of the routine's procedure entry mask --- that is, the address of
the routine itself.
AST-argument
VMS usage: user_arg
type: longword (unsigned)
access: read only
mechanism: by value
A value to be passed to the AST routine. The AST-argument is an
unsigned longword that contains the value to be passed to the AST
routine.
SMG$SET_CURSOR_ABS
The Set Absolute Cursor Position routine moves the virtual cursor to
the specified position in a virtual display.
Format:
SMG$SET_CURSOR_ABS display-id [,start-row] [,start-column]
Arguments:
display-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the virtual display in which to set the virtual cursor
position. The display-id argument is the address of an unsigned
longword that contains the display identifier.
start-row
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Specifies the row position to which the virtual cursor moves. The
start-row argument is the address of a signed longword integer that
contains the row number. If omitted, the cursor remains at the
current row.
start-column
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Specifies the column position to which the virtual cursor moves.
The start-column argument is the address of a signed longword
integer that contains the column number. If omitted, the virtual
cursor remains at the current column.
SMG$SET_CURSOR_MODE
The Turn the Physical Cursor On or Off and select Jump or Smooth
Scrolling routine turns the physical cursor on or off and selects
jump or smooth scrolling.
Format:
SMG$SET_CURSOR_MODE pasteboard-id ,flags
Arguments:
pasteboard-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Pasteboard identifier. The pasteboard-id argument is the address of
an unsigned longword that contains the pasteboard identifier.
flags
VMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Flag that determines mode to use. The flags argument is the address
of an unsigned longword that contains the flag. Flags accepts the
following values:
SMG$M_CURSOR_OFF Clears physical cursor.
SMG$M_CURSOR_ON Displays physical cursor.
SMG$M_SCROLL_JUMP Jump scrolls.
SMG$M_SCROLL_SMOOTH Smooth scrolls.
SMG$SET_CURSOR_REL
The Move Cursor Relative to Current Position routine moves the
virtual cursor the specified number of rows and columns from the
current virtual cursor position in a virtual display.
Format:
SMG$SET_CURSOR_REL display-id [,delta-row] [,delta-column]
Arguments:
display-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the virtual display in which to move the virtual cursor.
The display-id argument is the address of an unsigned longword that
contains the display identifier.
delta-row
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Specifies the number of rows to move the virtual cursor. The
delta-row argument is the address of a signed longword integer that
contains the number of rows to move. If omitted, the virtual cursor
remains at the current row position. If delta-row is positive, the
virtual cursor moves downward the specified number of rows. If
delta-row is negative, the virtual cursor moves upward the specified
number of rows.
delta-column
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Specifies the number of columns to move the cursor. The
delta-column argument is the address of a longword that contains the
number of columns to move. If omitted, the virtual cursor remains
at the current column position. If delta-column is positive, the
virtual cursor moves the specified number of columns to the right.
If delta-column is negative, the virtual cursor moves the specified
number of columns to the left.
SMG$SET_DEFAULT_STATE
The Set Default State routine sets and/or returns the current
default state for a key table.
Format:
SMG$SET_DEFAULT_STATE key-table-id [,new-state] [,old-state]
Arguments:
key-table-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the key table in which you are setting or inquiring about
a default state. The key-table-id argument is the address of an
unsigned longword that contains the key table identifier.
new-state
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
Specifies the new default state for the entire key table. The
new-state argument is the address of a descriptor pointing to the
new state string. The specified state name is converted to
uppercase and stripped of trailing blanks before use.
old-state
VMS usage: char_string
type: character string
access: write only
mechanism: by descriptor
Receives the existing default state name of the specified key
definition table. The old-state argument is the address of a
descriptor pointing to the storage into which the old state string
is written.
SMG$SET_DISPLAY_SCROLL_REGION
The Create Display Scrolling Region routine creates a scrolling
region in a virtual display.
Format:
SMG$SET_DISPLAY_SCROLL_REGION display-id [,start-row] [,end-row]
Arguments:
display-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the virtual display in which scrolling takes place. The
display-id argument is the address of an unsigned longword that
contains the display identifier.
start-row
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Specifies the first line of the scrolling region. The start-row
argument is the address of a signed longword integer that contains
the starting line number. If omitted, the first line of the display
is used.
end-row
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Specifies the last line of the scrolling region. The end-row
argument is the address of a signed longword integer that contains
the ending line number. If omitted, the last line of the virtual
display is used.
SMG$SET_KEYPAD_MODE
The Set Keypad Mode routine sets the terminal's numeric keypad to
either numeric or applications mode.
Format:
SMG$SET_KEYPAD_MODE keyboard-id ,flags
Arguments:
keyboard-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the virtual keyboard whose mode is to be changed. The
keyboard-id argument is the address of an unsigned longword that
contains the keyboard identifier.
flags
VMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies whether the keypad is to be in applications or numeric
mode. The flags argument is the address of an unsigned longword
that contains the new mode setting. If the low-order bit is clear,
the keypad is set to numeric mode; if the low-order bit is set, the
keypad is set to applications mode. All other bits must be zero.
SMG$SET_OUT_OF_BAND_ASTS
The Set Out-of-Band ASTs routine either enables or disables the
trapping of out-of-band control characters.
Format:
SMG$SET_OUT_OF_BAND_ASTS pasteboard-id ,control-character-mask
,AST-routine [,AST-argument]
Arguments:
pasteboard-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the terminal for which out-of-band characters are enabled
or disabled. The pasteboard-id argument is the address of an
unsigned longword that contains the pasteboard identifier.
Pasteboard-id is returned by SMG$CREATE_PASTEBOARD.
control-character-mask
VMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies which control characters are to be the new out-of-band
control characters. The control-character-mask argument is the
address of an unsigned longword that contains the mask. You create
this mask by setting the bit that corresponds to the ASCII value of
the desired character. For example, to specify that CTRL/C (ASCII
value 3) is an out-of-band control character, you set bit 3 (value
8) in the control-character-mask. If no bits are set in this mask,
then no out-of-band ASTs occur.
AST-routine
VMS usage: ast_procedure
type: procedure entry mask
access: read only
mechanism: by value
The address of an AST routine to be called when an out-of-band
control character is typed at the terminal. The AST-routine
argument is the address of the routine's procedure entry mask ---
that is, the address of the routine itself.
AST-argument
VMS usage: user_arg
type: longword (unsigned)
access: read only
mechanism: by value
The argument you supply for the AST. The AST-argument argument is
an unsigned longword that contains the value to be passed to the AST
routine. However, the AST routine may also need to know the
out-of-band character and the pasteboard-id at which it was typed.
Therefore, the Screen Management Facility creates a three-longword
structure to hold this information and passes the address of this
structure as the first argument to the AST routine. The remaining
four arguments are R0, R1, PC, and PSL. The Screen Management
Facility stores the argument you supply in this structure.
SMG$SET_PHYSICAL_CURSOR
The Set Cursor on Physical Screen routine moves the physical cursor
to the specified position on the physical screen.
Format:
SMG$SET_PHYSICAL_CURSOR pasteboard-id ,pasteboard-row
,pasteboard-column
Arguments:
pasteboard-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the physical screen whose physical cursor is to move. The
pasteboard-id argument is the address of an unsigned longword that
contains the pasteboard identifier.
pasteboard-row
VMS usage: longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Specifies the row to which the physical cursor moves. The
pasteboard-row argument is the address of a signed longword that
contains the row number.
pasteboard-column
VMS usage: longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Specifies the column to which the physical cursor moves. The
pasteboard-column argument is the address of a signed longword that
contains the column number.
SMG$SET_TERM_CHARACTERISTICS
The Change Terminal Characteristics routine changes or retrieves the
terminal characteristics for a given pasteboard.
Format:
SMG$SET_TERM_CHARACTERISTICS pasteboard-id
[,on-characteristics1] [,on-characteristics2]
[,off-characteristics1] [,off-characteristics2]
[,old-characteristics1] [,old-characteristics2]
Arguments:
pasteboard-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the pasteboard whose characteristics are to be changed or
retrieved. The pasteboard-id argument is the address of an unsigned
longword that contains the pasteboard identifier.
on-characteristics1
VMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Bit mask that specifies the terminal characteristics to be set from
$TTDEF. The on-characteristics1 argument is the address of an
unsigned longword that contains the bit mask.
on-characteristics2
VMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Bit mask that specifies the terminal characteristics to be set from
$TT2DEF. The on-characteristics2 argument is the address of an
unsigned longword that contains the bit mask.
off-characteristics1
VMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Bit mask that specifies the terminal characteristics to be reset
from $TTDEF. The off-characteristics1 argument is the address of an
unsigned longword that contains the bit mask.
off-characteristics2
VMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Bit mask that specifies the terminal characteristics to be reset
from $TT2DEF. The off-characteristics2 argument is the address of
an unsigned longword that contains the bit mask.
old-characteristics1
VMS usage: mask_longword
type: longword (unsigned)
access: write only
mechanism: by reference
Retrieves the current terminal characteristics in the first group.
The old-characteristics1 argument is the address of an unsigned
longword that contains the bit mask.
old-characteristics2
VMS usage: mask_longword
type: longword (unsigned)
access: write only
mechanism: by reference
Retrieves the current terminal characteristics in the second group.
The old-characteristics2 argument is the address of an unsigned
longword that contains the bit mask.
SMG$SNAPSHOT
The Write Snapshot routine writes the current pasteboard buffer to
the file or hardcopy terminal specified by pasteboard-id.
Format:
SMG$SNAPSHOT pasteboard-id [,flags]
ARGUMENT
pasteboard-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the file or hardcopy terminal to receive the contents of
the pasteboard buffer. The pasteboard-id argument is the address of
an unsigned longword that contains the pasteboard identifier. The
output device assiocated with pasteboard-id is specified by the
output-device argument of SMG$CREATE_PASTEBOARD.
flags
VMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Form-feed flag. The flags argument is the address of an unsigned
longword containing a Boolean value. If the value of flags is 1,
then the first record output will be a form feed (<FF>). If the
value of flags is zero, then an initial form-feed record will not be
output.
SMG$UNPASTE_VIRTUAL_DISPLAY
The Remove Virtual Display routine removes a virtual display from a
pasteboard.
Format:
SMG$UNPASTE_VIRTUAL_DISPLAY display-id ,pasteboard-id
Arguments:
display-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the virtual display to be removed from a pasteboard. The
display-id argument is the address of an unsigned longword that
contains the display identifier.
pasteboard-id
VMS usage: identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Specifies the pasteboard (physical screen) from which the virtual
display is removed. The pasteboard-id argument is the address of an
unsigned longword that contains the pasteboard identifier.
STR$
Additional information available:
STR$ADDSTR$ANALYZE_SDESCSTR$APPENDSTR$CASE_BLIND_COMPARE
STR$COMPARESTR$COMPARE_EQLSTR$COMPARE_MULTISTR$CONCAT
STR$COPY_DXSTR$COPY_RSTR$DIVIDESTR$DUPL_CHAR
STR$ELEMENTSTR$FIND_FIRST_IN_SETSTR$FIND_FIRST_NOT_IN_SET
STR$FIND_FIRST_SUBSTRINGSTR$FREE1_DXSTR$GET1_DX
STR$LEFTSTR$LEN_EXTRSTR$MATCH_WILDSTR$MULSTR$POSITION
STR$POS_EXTRSTR$PREFIXSTR$RECIPSTR$REPLACE
STR$RIGHTSTR$ROUNDSTR$TRANSLATESTR$TRIMSTR$UPCASE
STR$ADD
The Add Two Decimal Strings routine adds two decimal strings of
digits.
Format:
STR$ADD asign ,aexp ,adigits ,bsign ,bexp ,bdigits
,csign ,cexp ,cdigits
Arguments:
asign
VMS usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
Sign of the first operand. The asign argument is the address of an
unsigned longword containing this sign. Zero is considered
positive; 1 is considered negative.
aexp
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Power of 10 by which adigits has to be multiplied to get the
absolute value of the first operand. The aexp argument is the
address of a signed longword integer containing this exponent.
adigits
VMS usage: char_string
type: numeric string, unsigned
access: read only
mechanism: by descriptor
String of unsigned digits representing the absolute value of the
first operand before aexp is applied. The adigits argument is the
address of a descriptor pointing to this string. This string must
be an unsigned decimal number.
bsign
VMS usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
Sign of the second operand. The bsign argument is the address of an
unsigned longword containing the second operand's sign. Zero is
considered positive; one is considered negative. <endupdate_range>
bexp
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Power of 10 by which bdigits has to be multiplied to get the
absolute value of the second operand. The bexp argument is the
address of a signed longword integer containing the second operand's
exponent.
bdigits
VMS usage: char_string
type: numeric string, unsigned
access: read only
mechanism: by descriptor
String of unsigned digits representing the absolute value of the
second operand before bexp is applied. The bdigits argument is the
address of a descriptor pointing to this string. This string must
be an unsigned decimal number.
csign
VMS usage: longword_unsigned
type: longword (unsigned)
access: write only
mechanism: by reference
Sign of the result. The csign argument is the address of an
unsigned longword integer containing the result's sign. Zero is
considered positive.
cexp
VMS usage: longword_signed
type: longword integer (signed)
access: write only
mechanism: by reference
Power of 10 by which cdigits has to be multiplied to get the
absolute value of the result. The cexp argument is the address of a
signed longword integer containing the result's exponent.
cdigits
VMS usage: char_string
type: numeric string, unsigned
access: write only
mechanism: by descriptor
String of unsigned digits representing the absolute value of the
result before cexp is applied. The cdigits argument is the address
of a descriptor pointing to this string. This string is an unsigned
decimal number.
STR$ANALYZE_SDESC
The Analyze String Descriptor routine extracts the length and
starting address of the data for a variety of string descriptor
classes.
Format:
STR$ANALYZE_SDESC input-descriptor ,word-integer-length
,data-address
Arguments:
input-descriptor
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
Input descriptor from which STR$ANALYZE_SDESC extracts the length of
the data and the address at which the data starts. The
input-descriptor argument is the address of a descriptor pointing to
the input data.
word-integer-length
VMS usage: word_unsigned
type: word (unsigned)
access: write only
mechanism: by reference for CALL entry point,
by value for JSB entry point
Length of the data; this length is extracted from the descriptor by
STR$ANALYZE_SDESC. The word-integer-length argument is the address
of an unsigned word integer into which STR$ANALYZE_SDESC writes the
data length. for CALL entry point, by value for JSB entry point)
data-address
VMS usage: address
type: longword (unsigned)
access: write only
mechanism: by reference for CALL entry point,
by value for JSB entry point
Address of the data; this address is extracted from the descriptor
by STR$ANALYZE_SDESC. The data-address argument is an unsigned
longword into which STR$ANALYZE_SDESC writes the address of the
data.
STR$APPEND
The Append String routine appends a source string to the end of a
destination string. The destination string must be a dynamic or
varying string.
Format:
STR$APPEND destination-string ,source-string
Arguments:
destination-string
VMS usage: char_string
type: character string
access: write only
mechanism: by descriptor
Destination string to which STR$APPEND appends the source string.
The destination-string argument is the address of a descriptor
pointing to the destination string. This destination string must be
dynamic or varying.
source-string
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
Source string that STR$APPEND appends to the end of the destination
string. The source-string argument is the address of a descriptor
pointing to this source string.
STR$CASE_BLIND_COMPARE
The Compare Strings Without Regard to Case routine compares two
input strings of any supported class and data type without regard to
whether the alphabetic characters are uppercase or lowercase.
Format:
STR$CASE_BLIND_COMPARE first-source-string
,second-source-string
Arguments:
first-source-string
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
First string. The first-source-string argument is the address of a
descriptor pointing to the first string.
second-source-string
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
Second string. The second-source-string argument is the address of
a descriptor pointing to the second string.
STR$COMPARE
The Compare Two Strings routine compares the contents of two
strings. If the strings are unequal in length, the shorter string
is considered to be filled with blanks to the length of the longer
string before the comparison is made.
Format:
STR$COMPARE first-source-string ,second-source-string
Arguments:
first-source-string
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
First string. The first-source-string argument is the address of a
descriptor pointing to the first string.
second-source-string
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
Second string. The second-source-string argument is the address of
a descriptor pointing to the second string.
STR$COMPARE_EQL
The Compare Two Strings for Equality routine, compares two strings
to see if they have the same length and contents. Uppercase and
lowercase characters are not considered equal.
Format:
STR$COMPARE_EQL first-source-string ,second-source-string
Arguments:
first-source-string
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
First source string. The first-source-string argument is the
address of a descriptor pointing to the first source string.
second-source-string
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
Second source string. The second-source-string argument is the
address of a descriptor pointing to the second source string.
STR$COMPARE_MULTI
The Compare Two Strings for Equality Using Multinational Character
Set routine compares two character strings for equality using the
DEC Multinational character set.
Format:
STR$COMPARE_MULTI first-source-string ,second-source-string
[,flags-value] [,foreign-language]
Arguments:
first-source-string
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
First string in the comparison. The first-source-string argument is
the address of a descriptor pointing to the first string.
second-source-string
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
Second string in the comparison. The second-source-string argument
is the address of a descriptor pointing to the second string.
flags-value
VMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by value
A single flag bit. The flags-value argument is a signed longword
integer that contains this flag bit. The default value of
flags-value is zero.
Bit Symbol Meaning
0 CASEBLIND If set, uppercase and lowercase characters are
equivalent.
foreign-language
VMS usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by value
Indicator which determines the foreign language table to be used.
The foreign-language argument is an unsigned longword that contains
this foreign language table indicator. The default value of
foreign-language is 1.
Value Language
1 Multinational table
2 Danish table
3 Finnish/Swedish table
4 German table
5 Norwegian table
6 Spanish table
STR$CONCAT
The Concatenate Two or More Strings routine concatenates all
specified source strings into a single destination string. The
strings can be of any class and data type, provided that the length
fields of the descriptors indicate the strings' lengths in bytes.
You must specify at least one source string, and you may specify up
to 254 source strings. The maximum length of the concatenated
string is 65,535 bytes.
Format:
STR$CONCAT destination-string ,source-string
[,source-string...]
Arguments:
destination-string
VMS usage: char_string
type: character string
access: write only
mechanism: by descriptor
Destination string into which STR$CONCAT concatenates all specified
source strings. The destination-string argument is the address of a
descriptor pointing to this destination string.
source-string
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
First source string; STR$CONCAT requires at least one source string.
The source-string argument is the address of a descriptor pointing
to the first source string. The maximum number of source strings
that STR$CONCAT allows is 254.
source-string
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
Second source string; only the first source string is required.
The source-string argument is the address of a descriptor pointing
to the first source string. The maximum number of source strings
that STR$CONCAT allows is 254.
STR$COPY_DX
The Copy a Source String Passed by Descriptor to a Destination
String routine copies a source string to a destination string. Both
strings are passed by descriptor.
Format:
STR$COPY_DX destination-string ,source-string
Arguments:
destination-string
VMS usage: char_string
type: character string
access: write only
mechanism: by descriptor
Destination string into which STR$COPY_DX writes the source string;
depending on the class of the destination string, the following
actions occur:
Class Field Action
DSC$K_CLASS_S,Z,SD,A,NCA Copy the source string. If needed,
space is filled or truncated on
the right.
DSC$K_CLASS_D If the area specified by the
destination descriptor is large
enough to contain the source
string, copy the source string and
set the new length in the
destination descriptor. If the
area specified is not large
enough, return the previous space
allocation (if any) and then
dynamically allocate the amount of
space needed. Copy the source
string and set the new length and
address in the destination
descriptor.
DSC$K_CLASS_VS Copy source string to destination
string up to the limit of
DSC$W_MAXSTRLEN with no padding.
Readjust current length field to
actual number of bytes copied.
source-string
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
Source string that STR$COPY_DX copies into the destination string;
the descriptor class of the source string can be unspecified, fixed
length, dynamic, scalar decimal, array, noncontiguous array, or
varying.
STR$COPY_R
The Copy a Source String Passed by Reference to a Destination String
routine copies a source string passed by reference to a destination
string.
Format:
STR$COPY_R destination-string ,word-integer-source-length
,source-string-address
Arguments:
destination-string
VMS usage: char_string
type: character string
access: write only
mechanism: by descriptor
Destination string into which STR$COPY_R copies the source string.
The destination-string argument is the address of a descriptor
pointing to the destination string.
word-integer-source-length
VMS usage: word_unsigned
type: word (unsigned)
access: read only
mechanism: by reference
Length of the source string. The word-integer-source-length
argument is the address of an unsigned word containing the length of
the source string.
source-string-address
VMS usage: char_string
type: character string
access: read only
mechanism: by reference
Source string which STR$COPY_R copies into the destination string.
The source-string-address argument is the address of the source
string.
STR$DIVIDE
The Divide Two Decimal Strings routine divides two decimal strings.
Format:
STR$DIVIDE asign ,aexp ,adigits ,bsign ,bexp ,bdigits
,total-digits ,round-truncate-indicator ,csign ,cexp
,cdigits
Arguments:
asign
VMS usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
Sign of the first operand. The asign argument is the address of an
unsigned longword containing the first operand's sign. Zero is
considered positive; 1 is considered negative.
aexp
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Power of 10 by which adigits has to be multiplied to get the
absolute value of the first operand. The aexp argument is the
address of the first operand's exponent.
adigits
VMS usage: char_string
type: numeric string, unsigned
access: read only
mechanism: by descriptor
First operand's numeric string. The adigits argument is the address
of a descriptor pointing to the first operand's numeric string. The
string must be an unsigned decimal number.
bsign
VMS usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
Sign of the second operand. The bsign argument is the address of an
unsigned longword containing the second operand's string. Zero is
considered positive; 1 is considered negative.
bexp
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Power of 10 by which bdigits has to be multiplied to get the
absolute value of the second operand. The bexp argument is the
address of the second operand's exponent.
bdigits
VMS usage: char_string
type: numeric string, unsigned
access: read only
mechanism: by descriptor
Second operand's numeric string. The bdigits argument is the
address of a descriptor pointing to the second operand's number
string. The string must be an unsigned decimal number.
total-digits
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Number of digits to the right of the decimal point. The
total-digits argument is the address of a signed longword integer
containing the number of total digits. STR$DIVIDE uses this number
to carry out the division.
round-truncate-indicator
VMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Indicator of whether STR$DIVIDE is to round or truncate the result;
zero means truncate, 1 means round. The round-truncate-indicator
argument is the address of longword bit mask string containing this
indicator.
csign
VMS usage: longword_unsigned
type: longword (unsigned)
access: write only
mechanism: by reference
Sign of the result. The csign argument is the address of an
unsigned longword integer containing the sign of the result. Zero
is considered positive; 1 is considered negative.
cexp
VMS usage: longword_signed
type: longword integer (signed)
access: write only
mechanism: by reference
Power of 10 by which cdigits has to be multiplied to get the
absolute value of the result. The cexp argument is the address of a
signed longword integer containing the exponent.
cdigits
VMS usage: char_string
type: numeric string, unsigned
access: write only
mechanism: by descriptor
Result's numeric string. The cdigits argument is the address of a
descriptor pointing to the numeric string of the result. This
string is an unsigned decimal number.
STR$DUPL_CHAR
The Duplicate Character n Times routine generates a string
containing n duplicates of the input character. If the destination
string is an "empty" dynamic string descriptor, STR$DUPL_CHAR will
allocate and initialize the string.
Format:
STR$DUPL_CHAR destination-string [,longword-integer-length]
[,ASCII-character]
Arguments:
destination-string
VMS usage: char_string
type: character string
access: write only
mechanism: by descriptor
Destination string into which STR$DUPL_CHAR writes
longword-integer-length copies of the input character. The
destination-string argument is the address of a descriptor pointing
to the destination string.
longword-integer-length
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Number of times ASCII-character will be duplicated; this is an
optional argument (if omitted, the default is 1). The
longword-integer-length argument is the address of a signed longword
integer containing the number.
ASCII-character
VMS usage: char_string
type: character string
access: read only
mechanism: by reference
ASCII character that STR$DUPL_CHAR writes longword-integer-length
times into the destination string; this is an optional argument (if
omitted, the default is a space). The ASCII-character argument is
the address of a character string containing this character.
STR$ELEMENT
The Extract Delimited Element Substring routine extracts an element
from a string in which the elements are separated by a specified
delimiter.
Format:
STR$ELEMENT destination-string ,element-number
,delimiter-string ,source-string
Arguments:
destination-string
VMS usage: char_string
type: character string
access: write only
mechanism: by descriptor
Destination string into which STR$ELEMENT copies the selected
substring. The destination-string argument is the address of a
descriptor pointing to the destination string.
element-number
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Element number of the delimited element substring to be returned.
The element-number argument is the address of a signed longword
integer containing the desired element number. Zero is used to
represent the first delimited element substring, one is used to
represent the second, and so forth.
delimiter-string
VMS usage: char_string
type: character string
access: write only
mechanism: by descriptor
Delimiter string used to separate element substrings. The
delimiter-string argument is the address of a descriptor pointing to
the delimiter string. Delimiter-string must be exactly one
character long.
source-string
VMS usage: char_string
type: character string
access: write only
mechanism: by descriptor
Source string from which STR$ELEMENT extracts the requested
delimited substring. The source-string argument is the address of a
descriptor pointing to the source string.
STR$FIND_FIRST_IN_SET
The Find First Character in a Set of Characters routine searches a
string one character at a time, from left to right, comparing each
character in the string to every character in a specified set of
characters for which it is searching. STR$FIND_FIRST_IN_SET returns
the position in the string where the first matching character was
found. Zero is returned if no match is found.
Format:
STR$FIND_FIRST_IN_SET source-string ,set-of-characters
Arguments:
source-string
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
String which STR$FIND_FIRST_IN_SET compares to the set of
characters, looking for the first match. The source-string argument
is the address of a descriptor pointing to the character string.
set-of-characters
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
Set of characters which STR$FIND_FIRST_IN_SET is searching for in
the string. The source-string argument is the address of a
descriptor pointing to the set of characters.
STR$FIND_FIRST_NOT_IN_SET
The Find First Character that Does Not Occur in Set routine searches
a string, comparing each character to the characters in a specified
set of characters. The string is searched character by character,
from left to right. STR$FIND_FIRST_NOT_IN_SET returns the position
of the first character in the string that does not match any of the
characters in the selected set of characters.
Format:
STR$FIND_FIRST_NOT_IN_SET source-string ,set-of-characters
Arguments:
source-string
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
String which STR$FIND_FIRST_NOT_IN_SET searches. The source-string
argument is the address of a descriptor pointing to the string.
set-of-characters
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
The set of characters which STR$FIND_FIRST_NOT_IN_SET compares to
the string, looking for a nonmatch. The set-of-characters argument
is the address of a descriptor pointing to this set of characters.
STR$FIND_FIRST_SUBSTRING
The Find First Substring in Input String routine finds the first
substring (in a provided list of substrings) occurring in a given
string.
Format:
STR$FIND_FIRST_SUBSTRING source-string ,index
,sub-string-index ,sub-string [,sub-string...]
Arguments:
source-string
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
String that STR$FIND_FIRST_SUBSTRING searches. The source-string
argument is the address of a descriptor pointing to the string.
index
VMS usage: longword_signed
type: longword integer (signed)
access: write only
mechanism: by reference
Earliest position within source-string at which
STR$FIND_FIRST_SUBSTRING found a matching substring; zero if no
matching substring was found. The index argument is the address of
a signed longword integer containing this position.
sub-string-index
VMS usage: longword_signed
type: longword integer (signed)
access: write only
mechanism: by reference
Ordinal number of the sub-string that matched (1 for the first, 2
for the second, and so on), or zero if STR$FIND_FIRST_SUBSTRING
found no substrings that matched. The sub-string-index argument is
the address of a signed longword integer containing this ordinal
number.
sub-string
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
Specified substring for which STR$FIND_FIRST_SUBSTRING searches in
source-string. The source-string argument is the address of a
descriptor pointing to the first substring. You can specify
multiple substrings to be searched for.
sub-string
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
Specified substring for which STR$FIND_FIRST_SUBSTRING searches in
source-string. The source-string argument is the address of a
descriptor pointing to additional substrings. You can specify
multiple substrings to be searched for.
STR$FREE1_DX
The Free One Dynamic String routine deallocates one dynamic string.
Format:
STR$FREE1_DX string-descriptor
ARGUMENT
string-descriptor
VMS usage: char_string
type: character string
access: modify
mechanism: by descriptor
Dynamic string descriptor of the dynamic string which STR$FREE1_DX
deallocates. The string-descriptor argument is the address of a
descriptor pointing to the string to be deallocated. The class
field (DSC$B_CLASS) is checked.
STR$GET1_DX
The Allocate One Dynamic String routine allocates a specified number
of bytes of dynamic virtual memory to a specified dynamic string
descriptor.
Format:
STR$GET1_DX word-integer-length ,character-string
Arguments:
word-integer-length
VMS usage: word_unsigned
type: word (unsigned)
access: read only
mechanism: by reference
Number of bytes which STR$GET1_DX allocates. The
word-integer-length argument is the address of an unsigned word
containing this number.
character-string
VMS usage: char_string
type: character string
access: modify
mechanism: by descriptor
Dynamic string descriptor to which STR$GET1_DX allocates the area.
The character-string argument is the address of an unsigned quadword
containing the string descriptor.
STR$LEFT
The Extract a Substring of a String routine copies a substring of a
source string into a destination string.
Format:
STR$LEFT destination-string ,source-string ,end-position
Arguments:
destination-string
VMS usage: char_string
type: character string
access: write only
mechanism: by descriptor
Destination string into which STR$LEFT copies the substring. The
destination-string argument is the address of a descriptor pointing
to the destination string.
source-string
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
Source string from which STR$LEFT extracts the substring which it
copies into the destination string. The source-string argument is
the address of a descriptor pointing to the source string.
end-position
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Relative position in the source string at which the substring ends.
The end-position argument is the address of a signed longword
integer containing the ending position.
STR$LEN_EXTR
The Extract a Substring of a String routine copies a substring of a
source string into a destination string.
Format:
STR$LEN_EXTR destination-string ,source-string ,start-position
,longword-integer-length
Arguments:
destination-string
VMS usage: char_string
type: character string
access: write only
mechanism: by descriptor
Destination string into which STR$LEN_EXTR copies the substring.
The destination-string argument is the address of a descriptor
pointing to the destination string.
source-string
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
Source string from which STR$LEN_EXTR extracts the substring that it
copies into the destination string. The source-string argument is
the address of a descriptor pointing to the source string.
start-position
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Relative position in the source string at which the substring that
STR$LEN_EXTR copies starts. The start-position argument is the
address of a signed longword integer containing the starting
position.
longword-integer-length
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Number of characters in the substring that STR$LEN_EXTR copies to
the destination string. The longword-integer-length argument is the
address of a signed longword integer containing the length of the
substring.
STR$MATCH_WILD
The Match Wildcard Specification routine is used to compare a
pattern string that includes wildcard characters with a candidate
string. It returns a condition value of STR$_MATCH if the strings
match and STR$_NOMATCH if they do not match.
Format:
STR$MATCH_WILD candidate-string ,pattern-string
Arguments:
candidate-string
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
String to which the pattern string is compared. The
candidate-string argument is the address of a descriptor pointing to
the candidate string.
pattern-string
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
String containing wildcard characters. The pattern-string argument
is the address of a descriptor pointing to the pattern string. The
wildcards in the pattern string are translated when STR$MATCH_WILD
searches the candidate string to determine if it matches the pattern
string.
STR$MUL
The Multiply Two Decimal Strings routine multiplies two decimal
strings.
Format:
STR$MUL asign ,aexp ,adigits ,bsign ,bexp ,bdigits
,csign ,cexp ,cdigits
Arguments:
asign
VMS usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
Sign of the first operand. The asign argument is the address of an
unsigned longword containing the first operand's sign. Zero is
considered positive; 1 is considered negative.
aexp
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Power of 10 by which adigits has to be multiplied to get the
absolute value of the first operand. The aexp argument is the
address of a signed longword integer containing this exponent.
adigits
VMS usage: char_string
type: numeric string, unsigned
access: read only
mechanism: by descriptor
First operand's numeric string. The adigits argument is the address
of a descriptor pointing to the numeric string of the first operand.
The string must be an unsigned decimal number.
bsign
VMS usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
Sign of the second operand. The bsign argument is the address of an
unsigned longword containing the sign of the second operand. Zero
is considered positive; 1 is considered negative.
bexp
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Power of 10 by which bdigits has to be multiplied to get the
absolute value of the second operand. The bexp argument is the
address of a signed longword integer containing this exponent.
bdigits
VMS usage: char_string
type: numeric string, unsigned
access: read only
mechanism: by descriptor
Second operand's numeric string. The bdigits argument is the
address of a descriptor pointing to the second operand's numeric
string. The string must be an unsigned decimal number.
csign
VMS usage: longword_unsigned
type: longword (unsigned)
access: write only
mechanism: by reference
Sign of the result. The csign argument is the address of an
unsigned longword integer containing the sign of the result. Zero
is considered positive; 1 is considered negative.
cexp
VMS usage: longword_signed
type: longword integer (signed)
access: write only
mechanism: by reference
Power of 10 by which cdigits has to be multiplied to get the
absolute value of the result. The cexp argument is the address of a
signed longword integer containing this exponent.
cdigits
VMS usage: char_string
type: numeric string, unsigned
access: write only
mechanism: by descriptor
Result's numeric string. The cdigits argument is the address of a
descriptor pointing to the numeric string of the result. The string
will be an unsigned decimal number.
STR$POSITION
The Return Relative Position of Substring routine searches for the
first occurrence of a single substring within a source string. If
STR$POSITION finds the substring, it returns the relative position
of that substring. If the substring is not found, STR$POSITION
returns a zero.
Format:
STR$POSITION source-string ,sub-string [,start-position]
Arguments:
source-string
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
Source string within which STR$POSITION searches for the substring.
The source-string argument is the address of a descriptor pointing
to the source string.
sub-string
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
Substring for which STR$POSITION searches. The sub-string argument
is the address of a descriptor pointing to the substring.
start-position
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Relative position in the source string at which STR$POSITION begins
the search. The start-position argument is the address of a signed
longword integer containing the starting position. Although this is
an optional argument, it is required if you are using the JSB entry
point.
STR$POS_EXTR
The Extract a Substring of a String routine copies a substring of a
source string into a destination string.
Format:
STR$POS_EXTR destination-string ,source-string ,start-position
,end-position
Arguments:
destination-string
VMS usage: char_string
type: character string
access: write only
mechanism: by descriptor
Destination string into which STR$POS_EXTR copies the substring.
The destination-string argument is the address of a descriptor
pointing to the destination string.
source-string
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
Source string from which STR$POS_EXTR extracts the substring that it
copies into the destination string. The source-string argument is
the address of a descriptor pointing to the source string.
start-position
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference for CALL entry point,
by value for JSB entry point
Relative position in the source string at which the substring that
STR$POS_EXTR copies starts. The start-position argument is the
address of a signed longword integer containing the starting
position.
end-position
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference for CALL entry point,
by value for JSB entry point
Relative position in the source string at which the substring that
STR$POS_EXTR copies ends. The end-position argument is the address
of a signed longword integer containing the ending position.
STR$PREFIX
The Prefix a String routine inserts a source string at the beginning
of a destination string. The destination string must be dynamic or
varying.
Format:
STR$PREFIX destination-string ,source-string
Arguments:
destination-string
VMS usage: char_string
type: character string
access: write only
mechanism: by descriptor
Destination string (dynamic or varying); STR$PREFIX copies the
source string into the beginning of this destination string. The
destination-string argument is the address of a descriptor pointing
to the destination string.
source-string
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
Source string which STR$PREFIX copies into the beginning of the
destination string. The source-string argument is the address of a
descriptor pointing to the source string.
STR$RECIP
The Reciprocal of a Decimal String routine takes the reciprocal of
the first decimal string to the precision limit specified by the
second decimal string and returns the result as a decimal string.
Format:
STR$RECIP asign ,aexp ,adigits ,bsign ,bexp ,bdigits
,csign ,cexp ,cdigits
Arguments:
asign
VMS usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
Sign of the first operand. The asign argument is the address of an
unsigned longword containing the first operand's sign. Zero is
considered positive; 1 is considered negative.
aexp
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Power of 10 by which adigits has to be multiplied to get the
absolute value of the first operand. The aexp argument is the
address of a signed longword integer containing this exponent.
adigits
VMS usage: char_string
type: numeric string, unsigned
access: read only
mechanism: by descriptor
First operand's numeric string. The adigits argument is the address
of a descriptor pointing to the first operand's numeric string. The
string must be an unsigned decimal number.
bsign
VMS usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
Sign of the second operand. The bsign argument is the address of an
unsigned longword containing the sign of the second operand. Zero
is considered positive; 1 is considered negative.
bexp
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Power of 10 by which bdigits has to be multiplied to get the
absolute value of the second operand. The bexp argument is the
address of a signed longword integer containing this exponent.
bdigits
VMS usage: char_string
type: numeric string, unsigned
access: read only
mechanism: by descriptor
Second operand's numeric string. The bdigits argument is the
address of a descriptor pointing to the second operand's numeric
string. The string must be an unsigned decimal number.
csign
VMS usage: longword_unsigned
type: longword (unsigned)
access: write only
mechanism: by reference
Sign of the result. The csign argument is the address of an
unsigned longword integer containing the result's sign. Zero is
considered positive; 1 is considered negative.
cexp
VMS usage: longword_signed
type: longword integer (signed)
access: write only
mechanism: by reference
Power of 10 by which cdigits has to be multiplied to get the
absolute value of the result. The cexp argument is the address of a
signed longword integer containing this exponent.
cdigits
VMS usage: char_string
type: numeric string, unsigned
access: write only
mechanism: by descriptor
Result's numeric string. The cdigits argument is the address of a
descriptor pointing to the result's numeric string. The string will
be an unsigned decimal number.
STR$REPLACE
The Replace a Substring routine copies a source string to a
destination string, replacing part of the string with another
string. The substring to be replaced is specified by its starting
and ending positions.
Format:
STR$REPLACE destination-string ,source-string ,start-position
,end-position ,replacement-string
Arguments:
destination-string
VMS usage: char_string
type: character string
access: write only
mechanism: by descriptor
Destination string into which STR$REPLACE writes the new string
created when it replaces the substring. The destination-string
argument is the address of a descriptor pointing to the destination
string.
source-string
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
Source string. The source-string argument is the address of a
descriptor pointing to the source string.
start-position
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference for CALL entry point,
by value for JSB entry point
Position in the source string at which the substring which
STR$REPLACE replaces begins. The start-position argument is the
address of a signed longword integer containing the starting
position. The position is relative to the start of the source
string.
end-position
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference for CALL entry point,
by value for JSB entry point
Position in the source string at which the substring which
STR$REPLACE replaces ends. The end-position argument is the address
of a signed longword integer containing the ending position. The
position is relative to the start of the source string.
replacement-string
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
Replacement string with which STR$REPLACE replaces the substring.
The replacement-string argument is the address of a descriptor
pointing to this replacement string.
STR$RIGHT
The Extract a Substring of a String routine copies a substring of a
source string into a destination string.
Format:
STR$RIGHT destination-string ,source-string ,start-position
Arguments:
destination-string
VMS usage: char_string
type: character string
access: write only
mechanism: by descriptor
Destination string into which STR$RIGHT copies the substring. The
destination-string argument is the address of a descriptor pointing
to the destination string.
source-string
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
Source string from which STR$RIGHT extracts the substring that it
copies into the destination string. The source-string argument is
the address of a descriptor pointing to the source string.
start-position
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference for CALL entry point,
by value for JSB entry point
Relative position in the source string at which the substring that
STR$RIGHT copies starts. The start-position argument is the address
of a signed longword integer containing the starting position.
STR$ROUND
The Round or Truncate a Decimal String routine rounds or truncates a
decimal string to a specified number of significant digits and
places the result in another decimal string.
Format:
STR$ROUND places ,flags ,asign ,aexp ,adigits
,csign ,cexp ,cdigits
Arguments:
places
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Maximum number of decimal digits that STR$ROUND retains in the
result. The places argument is the address of a signed longword
integer containing the number of decimal digits.
flags
VMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Function flag. Zero indicates that the decimal string is rounded; 1
indicates that it is truncated. The flags argument is the address
of an unsigned longword containing this function flag.
asign
VMS usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
Sign of the first operand. The asign argument is the address of an
unsigned longword string containing this sign. A value of zero
indicates that the number is positive, while a value of 1 indicates
that the number is negative.
aexp
VMS usage: longword_signed
type: longword integer (signed)
access: read only
mechanism: by reference
Power of 10 by which adigits has to be multiplied to get the
absolute value of the first operand. The aexp argument is the
address of a signed longword integer containing this exponent.
adigits
VMS usage: char_string
type: numeric string, unsigned
access: read only
mechanism: by descriptor
First operand's numeric string. The adigits argument is the address
of a descriptor pointing to this numeric string. The string must be
an unsigned decimal number.
csign
VMS usage: longword_unsigned
type: longword (unsigned)
access: write only
mechanism: by reference
Sign of the result. The csign argument is the address of an
unsigned longword integer containing the result's sign. A value of
zero indicates that the number is positive, while a value of 1
indicates that the number is negative.
cexp
VMS usage: longword_signed
type: longword integer (signed)
access: write only
mechanism: by reference
Power of 10 by which cdigits has to be multiplied to get the
absolute value of the result. The cexp argument is the address of a
signed longword integer containing this exponent.
cdigits
VMS usage: char_string
type: numeric string, unsigned
access: write only
mechanism: by descriptor
Result's numeric string. The cdigits argument is the address of a
descriptor pointing to this numeric string. The string will be an
unsigned decimal number.
STR$TRANSLATE
The Translate Matched Characters routine successively compares each
character in a source string to all characters in a match string.
If a source character has a match, the destination character is
taken from the translate string. Otherwise, STR$TRANSLATE moves the
source character to the destination string.
Format:
STR$TRANSLATE destination-string ,source-string
,translation-string ,match-string
Arguments:
destination-string
VMS usage: char_string
type: character string
access: write only
mechanism: by descriptor
Destination string. The destination-string argument is the address
of a descriptor pointing to the destination string.
source-string
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
Source string. The source-string argument is the address of a
descriptor pointing to the source string.
translation-string
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
Translate string. The translation-string argument is the address of
a descriptor pointing to the translate string.
match-string
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
Match string. The match-string argument is the address of a
descriptor pointing to the match string.
STR$TRIM
The Trim Trailing Blanks and Tabs routine copies a source string to
a destination string and deletes the trailing blank and tab
characters.
Format:
STR$TRIM destination-string ,source-string [,resultant-length]
Arguments:
destination-string
VMS usage: char_string
type: character string
access: write only
mechanism: by descriptor
Destination string into which STR$TRIM copies the trimmed string.
The destination-string argument is the address of a descriptor
pointing to the destination string.
source-string
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
Source string which STR$TRIM trims and then copies into the
destination string. The source-string argument is the address of a
descriptor pointing to the source string.
resultant-length
VMS usage: word_unsigned
type: word (unsigned)
access: write only
mechanism: by reference
Number of bytes that STR$TRIM has written into destination-string,
not counting padding in the case of a fixed-length string. The
resultant-length argument is the address of an unsigned word into
which STR$TRIM writes the length of the output string. If the input
string is truncated to the size specified in the destination-string
description, resultant-length is set to this size. Therefore,
resultant-length can always be used by the calling program to access
a valid substring of destination-string.
STR$UPCASE
The Convert String to All Uppercase Characters routine converts a
source string to uppercase and writes the converted string into the
destination string. When you need to compare characters without
regard to case, you can first use STR$UPCASE to convert both
characters to uppercase. STR$UPCASE converts all characters in the
multinational character set.
Format:
STR$UPCASE destination-string ,source-string
Arguments:
destination-string
VMS usage: char_string
type: character string
access: write only
mechanism: by descriptor
Destination string into which STR$UPCASE writes the string it has
converted to uppercase. The destination-string argument is the
address of a descriptor pointing to the destination string.
source-string
VMS usage: char_string
type: character string
access: read only
mechanism: by descriptor
Source string that STR$UPCASE converts to uppercase. The
source-string argument is the address of a descriptor pointing to
the source string.
Specify
This help category contains information on the syntax of various entities used in DCL.
Additional information available:
Date TimeExpressionFile SpecIntegerPrivilegeProtectionString
Symbol
Date Time
When a command requires a qualifier that specifies a date/time value, the value is either an absolute time, a delta time, or a combination of the two.
Additional information available:
Absolute
Absolute time is a specific date and/or time of day.
An absolute date/time has one of the following formats:
[dd-mmm-yyyy[:]][hh:mm:ss.cc]
TODAY
YESTERDAY
TOMORROW
If you specify both the date and the time, the intervening colon
is required. You can omit any of the trailing fields in the date
or time. You can omit any of the fields in the middle of the
format as long as you specify the punctuation marks.
Combination
Combination time consists of an absolute time value plus or minus
a delta time value.
A combination time has the following format:
"[absolute time][+delta time]"
[absolute time][-delta time]
You can omit the absolute time value. If you do, the delta time
is offset from the current date and time. Whenever a plus sign
(+) precedes the delta time value, enclose the entire time
specification in quotes.
Delta
Delta time is an offset from the current time to a time in the
future. A delta time has the following format:
[dddd-] [hh:mm:ss.cc]
You can truncate delta time on the right. You can also omit any
of the fields in the middle of the format as long as you specify
the punctuation marks.
Expression
When DCL evaluates an expression, it determines a value based on the operations specified in the expression. The value can be an integer or a character string. Some expression operators are conventional mathematical symbols, for example, plus sign (+). Others specify logical and comparison operations, and consist of letters surrounded by periods, for example, .EQS. Operators are assigned a precedence which determines their order of evaluation. Parentheses may always be used to override this order.
Additional information available:
Arithmetic
The operator with the highest precedence in an expression is
evaluated first. Following this, the next highest operator is
evaluated, and so on. Operators with the same precedence are
evaluated from left to right, as they appear in the expression.
Operator Precedence Description
* 6 Arithmetic times
/ 6 Arithmetic divide
+ 5 Arithmetic plus
- 5 Arithmetic minus
.EQ. 4 Arithmetic equal
.GE. 4 Arithmetic greater than or equal
.GT. 4 Arithmetic greater than
.LE. 4 Arithmetic less than or equal
.LT. 4 Arithmetic less than
.NE. 4 Arithmetic not equal
.NOT. 3 Logical NOT
.AND. 2 Logical AND
.OR. 1 Logical OR
String
The operator with the highest precedence in an expression is
evaluated first. Following this, the next highest operator is
evaluated, and so on. Operators with the same precedence are
evaluated from left to right, as they appear in the expression.
Operator Precedence Description
+ 5 String concatenation
- 5 String reduction
.EQS. 4 String equal
.GES. 4 String greater than or equal
.GTS. 4 String greater than
.LES. 4 String less than or equal
.LTS. 4 String less than
.NES. 4 String not equal
File Spec
File specifications provide the system with the information
necessary to identify a unique file or device. A file spec has
the following format:
node::device:[directory]filename.type;version
The punctuation marks are required to separate the fields of the
file spec. These fields are:
node Network node name
device Device name
directory Directory name
filename File name
type File type
version File version number
Integer
DCL treats all numeric values as integers. If you do not specify
an explicit radix, numeric values are interpreted as decimal.
You may specify an explicit radix as follows:
%D1000 decimal radix
%O1357 octal radix
%X12AF hexadecimal radix
No blanks are allowed between the radix symbol and the number.
Privilege
Your set of privileges affects the system resources and system functions you are allowed to use.
Additional information available:
ACNTALLALLSPOOLALTPRIBUGCHKBYPASSCMEXEC
CMKRNLDETACHDIAGNOSEEXQUOTAGROUPGRPNAMGRPPRV
LOG_IOMOUNTNETMBXOPERPFNMAPPHY_IOPRMCEB
PRMGBLPRMMBXPSWAPMREADALLSECURITYSETPRVSHARE
SHMEMSYSGBLSYSLCKSYSNAMSYSPRVTMPMBXVOLPRO
WORLD
ACNT
Create a process for which no accounting is performed.
ALL
All privileges.
ALLSPOOL
Allocate spooled devices.
ALTPRI
Increase the base execution priority for any process.
BUGCHK
Make bug check error log entries.
BYPASS
Access resources without regard to UIC protection.
CMEXEC
Change mode to Executive.
CMKRNL
Change mode to Kernel.
DETACH
Create detached processes.
DIAGNOSE
Issue diagnostic I/O requests.
EXQUOTA
Exceed resource quotas.
GROUP
Control execution of other processes in the same group.
GRPNAM
Enter names in the group logical name table.
GRPPRV
Allow access to files in group along with the system category.
LOG_IO
Issue logical I/O requests.
MOUNT
Issue mount volume I/O requests.
NETMBX
Create a network device.
OPER
Perform system operator functions.
PFNMAP
Create or delete sections mapped by page frame.
PHY_IO
Issue physical I/O requests.
PRMCEB
Create permanent common event flag clusters.
PRMGBL
Create permanent global clusters.
PRMMBX
Create permanent mailbox devices.
PSWAPM
Change process swap mode.
READALL
Bypass restrictions otherwise preventing process from reading a file.
SECURITY
Perform security-related functions.
SETPRV
Grant a process any privilege.
SHARE
Assign a channel to a device.
SHMEM
Create or delete data structures in shared memory.
SYSGBL
Create system global sections.
SYSLCK
Request locks on system resources.
SYSNAM
Enter names in the system logical name table.
SYSPRV
Access resources as if the process has a system UIC.
TMPMBX
Create temporary mailbox devices.
VOLPRO
Override protection on a volume.
WORLD
Control the execute of any process on the system.
Protection
Volume and file protection is specified as follows:
(SYSTEM:rwed,OWNER:rwed,GROUP:rwed,WORLD:rwed)
There are four categories of protection, one for system
processes, one for the owner of the file, one for other members
of the owner's group, and one for members of other groups. For
each category, any combination of four different types of access
may be specified:
R - read access
W - write access
E - execute access (for execution of images)
D - delete access
If you want to deny all access to a category, you must specify
the category name without a colon, for example:
/PROTECTION=(OWNER:RWE,GROUP,WORLD)
String
A character string value is represented as a sequence of
characters enclosed in quotation marks ("). A quotation mark in
a character string must be represented by two quotation marks.
In certain contexts, the quotation marks are optional.
Symbol
A symbol is an entity which has a name and a value. The name can consist of the letters, digits, underscore (_) and dollar sign ($). It can be composed of up to 255 characters. The value of the symbol can be a 32-bit integer or a string of between zero and 255 characters. Symbols are defined in DCL with the assignment statement. This is described under the HELP SYMBOL_ASSIGN.
UIC
A UIC is a User Identification Code and can be in either numeric or
named format. When a DCL command requires a UIC specification, you
can specify either format. However, the system converts all UIC's
to numeric format when determining a user's access to a data resource.
A UIC in numeric format consists of a group number and a member number
in the format:
[group,member]
where:
group is an octal number in the range 0 through 37776
representing the group number.
member is an octal number in the range 0 through 37776
representing the member number.
The square brackets are required in the UIC specification. You may also
omit leading zeros when specifying group and member numbers.
A UIC in named format consists of a member identifier and, optionally, a
group identifier, as shown below:
[member]
[group,member]
The group and member identifiers can each contain up to 31 alphanumeric
characters and must contain at least one alphabetic character. The names
can include the characters A through Z, dollar signs ($) and underscores
(_), and the numbers 0 through 9. The brackets are required in the UIC
specification.
The member number is unique for each for each user on the system, and is
equivalent to the user's numeric UIC (including both the group and the
member numbers). The group identifier is equivalent to only the group
portion of the UIC.
Symbol Assign
Defines a symbolic name for a character string or integer value.
Format:
symbol-name =[=] expression
symbol-name[bit-position,size] =[=] replacement-expression
Additional information available:
ParametersExamplesString Assign
Parameters
symbol-name Defines a 1- through 255-character alphanumeric string name for the symbol. The symbol name must begin with an alphabetic character (uppercase and lowercase characters are equivalent), an underscore, or a dollar sign. After the first character, the name can contain any alphanumeric characters from the DEC multinational character set, underscores, or dollar signs. If you specify a single equal sign (=) in the assignment statement, the symbol name is placed in the local symbol table for the current command level. If you specify double equal signs (==) in the assignment statement, the symbol name is placed in the global symbol table. expression Specifies the value on the right-hand side of an assignment statement. An expression can consist of a character string value, an integer value, a symbol name, a lexical function, or a combination of these entities. The components of an expression are evaluated, and the result is assigned to a symbol. All literal character strings must be enclosed in quotation marks. If you specify an expression containing a symbol, the command interpreter uses the symbol's value in evaluating the expression. The result of expression evaluation is either a character string or an integer value. The data type of a symbol is determined by the data type of the expression. If the expression evaluates to a string, the symbol is assigned a string value. If the expression evaluates to an integer, the symbol is assigned an integer value. For a summary of operators used in expressions, details on how to specify expressions, and details on how expressions are evaluated, see the VMS DCL Concepts Manual. DCL uses a buffer that is 1024 bytes long to hold an assignment statement, and to evaluate the expression. The length of the symbol name, the expression, and the expression's calculations cannot exceed 1024 bytes. [bit-position,size] Specifies that a binary overlay is to be inserted in the current 32-bit value of a symbol-name. This type of assignment statement evaluates the current value of the symbol-name and replaces the specified number of bits with the result of the replacement-expression. The bit-position is the location relative to bit 0 at which the overlay is to occur. If the symbol that you are overlaying is an integer, then the bit position must be less than 32. Also, the sum of the bit position and the size must be less than or equal to 32. If the symbol you are overlaying is a string, then the bit position must be less than 6152. Because each character is represented using 8 bits, you can begin an overlay at any character through the 768th. (The 768th character starts in bit position 6144.) The sum of the bit position and the size must be less than or equal to 6152. The size is the number of bits to be overlaid. If you specify a size that is greater than 32, then DCL reduces the size to 32. The square brackets are required notation; no spaces are allowed between the symbol name and the left bracket. Specify values for bit-position and size as integer expressions. replacement-expression Specifies the value that is used to overlay the symbol you are modifying. Specify the replacement-expression as an integer expression. If the symbol you are modifying is an integer, the replacement-expression defines a bit pattern which is overlaid on the value assigned to the symbol. If the symbol you are modifying is a character string, the result of the replacement-expression defines a bit pattern which is overlaid on the specified bits of the character string. If the symbol you are modifying is undefined, the result of the replacement-expression is overlaid on a null string.
Examples
1. $ LIST == "DIRECTORY"
$ TIME == "SHOW TIME"
$ QP == "SHOW QUEUE/DEVICE"
$ SS == "SHOW SYMBOL"
The file SYNONYM.COM contains the assignment statements shown;
these are user-defined synonyms for commands. Execute this command
procedure as follows:
$ @SYNONYM
After the command procedure creates the global symbol definitions,
you can use these synonyms (LIST, TIME, QP,and SS) at the
interactive command level. Note that the assignments are global;
otherwise, the symbol names would have been deleted after the file
SYNONYM.COM completed execution.
2. $ COUNT = 0
$ LOOP:
$ COUNT = COUNT + 1
.
.
.
$ IF COUNT .LT.5 THEN GOTO LOOP
The symbol COUNT is initially assigned a numeric value of 0; a loop
is established to increment the value of COUNT by 1 each time the
loop is entered. Note that when the symbol name COUNT appears on
the right-hand side of an arithmetic assignment statement, the
command interpreter automatically substitutes its current value.
The IF command tests the value of COUNT; if it is less than 5, the
procedure branches to the label LOOP and the statements between the
label LOOP through the IF command are executed again. When the
value of the symbol count reaches 5, the loop is not executed again
and the command following the IF command is executed.
3. $ A = 25
$ CODE = 4 + F$INTEGER("6") - A
$ SHOW SYMBOL CODE
CODE = -15 HEX = FFFFFFF1 Octal = 1777761
This example contains two assignment statements. The first
statement assigns the value 25 to the symbol A. The second
assignment statement evaluates an expression containing an integer
(4), a lexical function (F$INTEGER("6")), and the symbol A. The
result of the expression, -15, is assigned to the symbol CODE.
String Assign
Defines a symbolic name for a character string value.
Format:
symbol-name :=[=] string
symbol-name[offset,size] :=[=] replacement-string
Additional information available:
Parameters
symbol-name
Defines a 1- through 255-character string name for the symbol. The
symbol name must begin with an alphabetic character (uppercase and
lowercase characters are equivalent), an underscore, or a dollar
sign. After the first character, the name can contain any
alphanumeric characters from the DEC Multinational Character Set,
underscores, or dollar signs.
If you specify a single equal sign (:=) in the assignment statement,
the symbol name is placed in the local symbol table for the current
command level.
If you specify double equal signs (:==) in the assignment statement,
the symbol name is placed in the global symbol table.
string
Specifies a character string value to be equated to the symbol. The
string can contain any alphanumeric or special characters. DCL uses
a buffer that is 1024 bytes long to hold a string assignment
statement, Therefore, the length of the symbol name, the string, and
any symbol substitution within the string cannot exceed 1024
characters.
With the := string assignment statement, you do not need to enclose
a string literal in quotation marks. String values are
automatically converted to uppercase. Also, any leading and
trailing spaces and tabs are removed, and multiple spaces and tabs
between characters are compressed to a single space.
Note that, in general, it is easier to use the assignment statement
(=) to create symbols with string values. The assignment statement
does not automatically capitalize and remove extra spaces. Also,
the assignment statement allows you to perform string operations
in expressions.
If you want to prohibit uppercase conversion and retain required
space and tab characters in a string, you must place quotation marks
around the string. To use quotation marks in a string, enclose the
entire string in quotation marks and use a double set of quotation
marks within the string. For example:
$ TEST := "this is a ""test"" string"
$ SHOW SYMBOL TEST
TEST = "this is a "test" string"
In this example, the spaces, lowercase letters, and quotation marks
are preserved in the symbol definition.
You can continue a symbol assignment on more than one line by using
the hyphen as a continuation character. For example:
$ LONG_STRING := THIS_IS_A_VERY_LONG-
_$ _SYMBOL_STRING
To assign a null string to a symbol using the string assignment
statement, do not specify a string. For example:
$ NULL :=
Specify the string as a string literal, or as a symbol or lexical
function which evaluates to a string literal. If you use symbols or
lexical functions, place apostrophes around them to request symbol
substitution.
You can also use the string assignment statement to define a foreign
command. See the VMS DCL Concepts Manual for more information on
symbol substitution and foreign commands.
[offset,size]
Specifies that a portion of a symbol value is to be overlaid with a
replacement string. This form of the string assignment statement
evaluates the value assigned to a symbol-name and then replaces the
portion of the value (defined by the offset and size) with the
replacement string. The square brackets are required notation, and
no spaces are allowed between the symbol name and the left bracket.
The offset specifies the character position relative to the
beginning of the symbol-name's string value at which replacement is
to begin. Offset values start at 0.
If the offset is greater than the offset of the last character in
the string you are modifying, spaces are inserted between the end of
the string and the offset where the replacement string is added.
The maximum offset value you can specify is 768.
The size specifies the number of characters to replace. Size values
start at 1.
Specify the offset and size as integer expressions. See the VMS
DCL Concepts Manual for more information on integer expressions. The
value of the size plus the offset must not exceed 769.
replacement-string
Specifies the string that is used to overlay the string you are
modifying. If the replacement-string is shorter than the size
argument, the replacement string is blank-filled on the right until
it equals the specified size. Then the replacement string is used
to overlay the string assigned to the symbol-name. If the
replacement string is longer than the size argument, then the
replacement string is truncated on the right to the specified size.
You can specify the replacement-string as a string literal, or as a
symbol or lexical function which evaluates to a string literal. If
you use symbols or lexical functions, place apostrophes around them
to request symbol substitution. See the VMS DCL Concepts Manual
for more information on symbol substitution.
Examples
1. $ TIME := SHOW TIME
$ TIME
15-APR-1987 11:55:44
The symbol TIME is equated to the command string SHOW TIME. Because
the symbol name appears as the first word in a command string, the
command interpreter automatically substitutes it with its string
value and executes the command SHOW TIME.
2. $ STAT := $DBA1:[CRAMER]STAT
$ STAT
This example shows how to define STAT as a foreign command. The
symbol STAT is equated to a string that begins with a dollar sign
followed by a file specification. The command interpreter assumes
that the file specification is that of an executable image, that is,
a file with a file type of EXE. Thus, the symbol STAT in this
example becomes a synonym for the command:
$ RUN DBA1:[CRAMER]STAT.EXE
When you subsequently type STAT, the command interpreter executes
the image.
3. $ A = "this is a big space."
$ SHOW SYMBOL A
A = "this is a big space."
$ B := 'A'
$ SHOW SYMBOL B
B = "THIS IS A BIG SPACE."
This example compares the assignment and the string assignment
statements. The symbol A is defined using the assignment statement,
so lowercase letters and multiple spaces are retained. The symbol B
is defined using the string assignment statement. Note that the
apostrophes are required; otherwise, the symbol name B would have
been equated to the literal string A. However, when symbol A's
value is assigned to symbol B, the letters are converted to
uppercase and multiple spaces are compressed.
System Services
This help category provides an overview and the format of each of the VMS system services.
Additional information available:
$ABORT_TRANS$ABORT_TRANSW$ASSIGN$CREMBX$END_TRANS
$END_TRANSW$GETQUI$GETQUIW$QIO$SNDJBC$SNDJBCW
$START_TRANS$START_TRANSW
$ABORT_TRANS
Aborts a transaction.
Format
SYS$ABORT_TRANS [efn] ,[flags] ,iosb [,[astadr] ,[astprm]
,[tid] ,[reason]]
Arguments
efn
VMS Usage: ef_number
type: longword (unsigned)
access: read only
mechanism: by value
Number of the event flag to be set. The efn argument is a longword
containing this number; however, $ABORT_TRANS uses only the low-
order byte. If you do not specify the efn, $ABORT_TRANS uses the
default value 0.
flags
VMS Usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by value
Flags specifying options for $ABORT_TRANS. The flags argument is a
longword bit mask that is the logical OR of each bit set, in which
each bit corresponds to an option. The $DDTMDEF macro defines a
symbolic name for each flag bit.
Table 1 $ABORT_TRANS Option Flag
Flag Description
DDTM$M_SYNC Indicates successful synchronous completion by
returning SS$_SYNCH. When synchronous completion
is successful, the completion AST address is not
called, the IOSB is not written, and the event
flag is not set.
iosb
VMS Usage: io_status_block
type: quadword (unsigned)
access: write only
mechanism: by reference
I/O status block (IOSB) to receive the final completion status of
the request. The iosb argument is the address of the quadword I/O
status block.
astadr
VMS Usage: ast_procedure
type: procedure entry mask
access: call without stack unwinding
mechanism: by reference
AST service routine to be executed. The astadr argument is
the address of the entry mask of this routine. In the case of
synchronous completion, the call might not take place.
astprm
VMS Usage: user_arg
type: longword (unsigned)
access: read only
mechanism: by value
AST parameter passed to the AST service routine specified by the
astadr argument. The astprm argument is a longword.
tid
VMS Usage: transaction_id
type: octaword (unsigned)
access: read only
mechanism: by reference
Pointer to the transaction identifier (TID) that designates the
transaction to be aborted. The default value for this parameter is
the process default transaction.
reason
VMS Usage: cond_value
type: longword (unsigned)
access: read only
mechanism: by value
The reason why the calling process is aborting the transaction.
This must be a valid abort reason code. Symbolic names for the
valid abort reason codes are defined in the $DDTMMSGDEF module.
$ABORT_TRANSW
Aborts a transaction.
$ABORT_TRANSW completes synchronously; that is, it returns to the
caller after the request has completed.
For asynchronous completion, use the Abort Transaction ($ABORT_
TRANS) service, which returns without waiting for the operation to
complete.
In all other respects, $ABORT_TRANSW is identical to $ABORT_TRANS.
For all other information about the $ABORT_TRANSW service, refer
to the section on $ABORT_TRANS.
Format
SYS$ABORT_TRANSW [efn] ,[flags] ,iosb [,[astadr] ,[astprm]
,[tid] ,[reason]]
$ASSIGN
Provides a process with an I/O channel so that input/output
operations can be performed on a device, or establishes a logical
link with a remote node on a network.
Format
SYS$ASSIGN devnam ,chan ,[acmode] ,[mbxnam] ,[flags]
Arguments
devnam
VMS Usage: device_name
type: character-coded text string
access: read only
mechanism: by descriptor-fixed length string descriptor
Name of the device to which $ASSIGN is to assign a channel. The
devnam argument is the address of a character string descriptor
pointing to the device name string.
chan
VMS Usage: channel
type: word (unsigned)
access: write only
mechanism: by reference
Number of the channel that is assigned. The chan argument is the
address of a word into which $ASSIGN writes the channel number.
acmode
VMS Usage: access_mode
type: longword (unsigned)
access: read only
mechanism: by value
Access mode to be associated with the channel. The acmode argument
specifies the access mode. The $PSLDEF macro defines the following
symbols for the four access modes.
mbxnam
VMS Usage: device_name
type: character-coded text string
access: read only
mechanism: by descriptor-fixed length string descriptor
Logical name of the mailbox to be associated with the device. The
mbxnam argument is the address of a character string descriptor
pointing to the logical name string.
flags
VMS Usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by value
The flags argument is an optional device-specific argument. It is
a longword bit mask.
$CREMBX
Creates a virtual mailbox device named MBAn and assigns an I/O
channel to it. The system provides the unit number n when it
creates the mailbox. If a logical name is specified and a mailbox
with the specified name already exists, the $CREMBX service
assigns a channel to the existing mailbox.
Format
SYS$CREMBX [prmflg] ,chan ,[maxmsg] ,[bufquo] ,[promsk]
,[acmode] ,[lognam] ,[flags]
Arguments
prmflg
VMS Usage: boolean
type: byte (unsigned)
access: read only
mechanism: by value
Indicator specifying whether the created mailbox is to be
permanent or temporary. The prmflg argument is a byte value. The
value 1 specifies a permanent mailbox; the value 0, which is the
default, specifies a temporary mailbox. Any other values result in
an error.
chan
VMS Usage: channel
type: word (unsigned)
access: write only
mechanism: by reference
Cbhannel number assigned by $CREMBX to the mailbox. The chan
argument is the address of a word into which $CREMBX writes the
channel number.
maxmsg
VMS Usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by value
Maximum size (in bytes) of a message that can be sent to the
mailbox. The maxmsg argument is a longword value containing this
size. If you do not specify maxmsg or specify it as 0, the VMS
operating system provides a default value.
bufquo
VMS Usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by value
Number of bytes of system dynamic memory that can be used to
buffer messages sent to the mailbox. The bufquo argument is a word
value containing this number. If you do not specify the bufquo
argument or specify it as 0, VMS provides a default value.
promsk
VMS Usage: file_protection
type: longword (unsigned)
access: read only
mechanism: by value
Protection mask to be associated with the created mailbox. The
promsk argument is a longword value that is the combined value of
the bits set in the protection mask. Cleared bits grant access and
set bits deny access to each of the four classes of user: world,
group, owner, and system. The following diagram depicts these
protection bits.
acmode
VMS Usage: access_mode
type: longword (unsigned)
access: read only
mechanism: by value
Access mode to be associated with the channel to which the mailbox
is assigned. The acmode argument is a longword containing the
access mode.
lognam
VMS Usage: logical_name
type: character-coded text string
access: read only
mechanism: by descriptor-fixed length string descriptor
Logical name to be assigned to the mailbox. The lognam argument
is the address of a character string descriptor pointing to the
logical name string.
$END_TRANS
Initiates processing commitment for the transaction. This service
performs both phases of the commitment. Consequently, it returns
a failure status (SS$_ABORT) if the first of the phases does
not complete successfully or if an error occurs that makes it
impossible to commit the transaction.
Format
SYS$END_TRANS [efn] ,[flags] ,iosb [,[ astadr] ,[astprm]
,[tid]]
Arguments
efn
VMS Usage: ef_number
type: longword (unsigned)
access: read only
mechanism: by value
Number of the event flag to be set. The efn argument is a longword
containing this number; however, $END_TRANS uses only the low-
order byte. If you do not specify efn, $END_TRANS uses the default
value 0.
flags
VMS Usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by value
Flags specifying options for $END_TRANS. The flags argument is a
longword bit mask that is the logical OR of each bit set, in which
each bit corresponds to an option. The $DDTMDEF macro defines a
symbolic name for each flag bit.
Table 1 $END_TRANS Option Flag
Flag Description
DDTM$M_SYNC Indicates successful synchronous completion by
returning SS$_SYNCH. When synchronous completion
is successful, the completion AST address is not
called, the IOSB is not written, and the event
flag is not set.
iosb
VMS Usage: io_status_block
type: quadword (unsigned)
access: write only
mechanism: by reference
I/O status block (IOSB) to receive the final completion status of
the request. The iosb argument is the address of the quadword I/O
status block. If the transaction ends by being aborted, an abort
reason code is returned in the IOSB.
astadr
VMS Usage: ast_procedure
type: procedure entry mask
access: call without stack unwinding
mechanism: by reference
AST service routine to be executed when the $END_TRANS service
completes. The astadr argument is the address of the entry mask
of this routine. In the case of synchronous completion, the call
might not take place.
astprm
VMS Usage: user_arg
type: longword (unsigned)
access: read only
mechanism: by value
AST parameter passed to the AST service routine specified by the
astadr argument. The astprm argument is a longword.
tid
VMS Usage: transaction_id
type: octaword (unsigned)
access: read only
mechanism: by reference
Pointer to the transaction identifier (TID) that designates the
transaction to be ended.
$END_TRANSW
Initiates processing commitment for the transaction. This service
performs both phases of the commitment. Consequently, it returns
a failure status (SS$_ABORT) if the first of the phases does
not complete successfully or if an error occurs that makes it
impossible to commit the transaction.
$END_TRANSW completes synchronously; that is, it returns to the
caller after the request has completed.
For asynchronous completion, you use the End Transaction
($END_TRANS) system service, which returns without waiting for
the operation to complete.
In all other respects, $END_TRANSW is identical to $END_TRANS. For
all other information about $END_TRANSW, refer to the section on
$END_TRANS.
For additional information about system service completion, refer
to the Synchronize ($SYNCH) service and to the Introduction to VMS
System Services.
Format
SYS$END_TRANSW [efn] ,[flags] ,iosb [,[astadr] ,[astprm]
,[tid]]
$GETQUI
Returns information about queues and the jobs initiated from those
queues.
The $GETQUI service completes asynchronously; for synchronous
completion, you use the Get Queue Information and Wait ($GETQUIW)
service.
Format
SYS$GETQUI [efn] ,func [,nullarg] [,itmlst] [,iosb] [,astadr]
[,astprm]
Arguments
efn
VMS Usage: ef_number
type: longword (unsigned)
access: read only
mechanism: by value
Number of the event flag to be set when $GETQUI completes. The efn
argument is a longword containing this number; however, $GETQUI
uses only the low-order byte. The efn argument is optional.
func
VMS Usage: function_code
type: word (unsigned)
access: read only
mechanism: by value
Function code specifying the function that $GETQUI is to perform.
The func argument is a word containing this function code. The
$QUIDEF macro defines the names of each function code.
nullarg
VMS Usage: null_arg
type: longword (unsigned)
access: read only
mechanism: by value
Placeholding argument reserved by Digital.
itmlst
VMS Usage: item_list_3
type: longword (unsigned)
access: read only
mechanism: by reference
Item list supplying information to be used in performing the
function specified by the func argument. The itmlst argument is
the address of the item list. The item list consists of one or
more item descriptors, each of which contains an item code. The
item list is terminated by an item code of 0 or by a longword of
0.
iosb
VMS Usage: io_status_block
type: quadword (unsigned)
access: write only
mechanism: by reference
I/O status block into which $GETQUI writes the completion status
after the requested operation has completed. The iosb argument is
the address of the I/O status block.
astadr
VMS Usage: ast_procedure
type: procedure entry mask
access: call without stack unwinding
mechanism: by reference
AST service routine to be executed when $GETQUI completes. The
astadr argument is the address of the entry mask of this routine.
astprm
VMS Usage: user_parm
type: longword (unsigned)
access: read only
mechanism: by value
AST parameter to be passed to the AST service routine specified
by the astadr argument. The astprm argument is this longword
parameter.
$GETQUIW
Returns information about queues and jobs initiated from those
queues. The $SNDJBC service is the major interface to the VMS
Job Controller, which is the VMS queue and accounting manager.
For a discussion of the different types of job and queue, see the
Description section of $SNDJBC.
The $GETQUIW service completes synchronously; that is, it returns
to the caller with the requested information. For asynchronous
completion, you use the Get Queue Information ($GETQUI) service;
$GETQUI returns to the caller after queuing the information
request, without waiting for the information to be returned.
In all other respects, $GETQUIW is identical to $GETQUI.
Format
SYS$GETQUIW [efn] ,func [,nullarg] [,itmlst] [,iosb] [,astadr]
[,astprm]
$QIO
Queues an I/O request to a channel associated with a device. This
service completes asynchronously; for synchronous completion, use
the Queue I/O Request and Wait ($QIOW) service.
Format
SYS$QIO [efn] ,chan ,func [,iosb] [,astadr] [,astprm] [,p1]
[,p2] [,p3] [,p4] [,p5] [,p6]
Arguments
efn
VMS Usage: ef_number
type: longword (unsigned)
access: read only
mechanism: by value
Event flag that $QIO is to set when the I/O operation completes.
The efn argument is a longword value containing the number of the
event flag; however, $QIO uses only the low-order byte.
chan
VMS Usage: channel
type: longword (unsigned)
access: read only
mechanism: by value
I/O channel assigned to the device to which the request is
directed. The chan argument is a longword value containing the
number of the I/O channel; however, $QIO uses only the low-order
word.
func
VMS Usage: function_code
type: longword (unsigned)
access: read only
mechanism: by value
Device-specific function codes and function modifiers specifying
the operation to be performed. The func argument is a longword
containing the function code.
iosb
VMS Usage: io_status_block
type: quadword (unsigned)
access: write only
mechanism: by reference
I/O status block to receive the final completion status of the I/O
operation. The iosb argument is the address of the quadword I/O
status block.
astadr
VMS Usage: ast_procedure
type: procedure entry mask
access: call without stack unwinding
mechanism: by reference
AST service routine to be executed when the I/O completes. The
astadr argument is the address of a longword value that is the
entry mask to the AST routine.
astprm
VMS Usage: user_arg
type: longword (unsigned)
access: read only
mechanism: by value
AST parameter to be passed to the AST service routine. The astprm
argument is a longword value containing the AST parameter.
p1 to p6
VMS Usage: varying_arg
type: longword (unsigned)
access: read only
mechanism: by reference or by value depending on the I/O function
Optional device- and function-specific I/O request parameters.
$SNDJBC
Creates, stops, and manages queues and the batch and print jobs
in those queues. The $SNDJBC service completes asynchronously; to
synchronize the completion of most operations, you use the Send to
Job Controller and Wait ($SNDJBCW) service.
Format
SYS$SNDJBC [efn] ,func [,nullarg] [,itmlst] [,iosb] [,astadr]
[,astprm]
Arguments
efn
VMS Usage: ef_number
type: longword (unsigned)
access: read only
mechanism: by value
Number of the event flag to be set when $SNDJBC completes. The efn
argument is a longword containing this number; however, $SNDJBC
uses only the low-order byte.
nullarg
VMS Usage: null_arg
type: longword (unsigned)
access: read only
mechanism: by value
Placeholding argument reserved by Digital.
itmlst
VMS Usage: item_list_3
type: longword (unsigned)
access: read only
mechanism: by reference
Item list supplying information to be used in performing the
function specified by the func argument. The itmlst argument is
the address of the item list. The item list consists of one or
more item descriptors, each of which specifies an item code. The
item list is terminated by an item code of 0 or by a longword of
0.
iosb
VMS Usage: io_status_block
type: quadword (unsigned)
access: write only
mechanism: by reference
I/O status block into which $SNDJBC writes the completion status
after the requested operation has completed. The iosb argument is
the address of the I/O status block.
astadr
VMS Usage: ast_procedure
type: procedure entry mask
access: call without stack unwinding
mechanism: by reference
AST service routine to be executed when $SNDJBC completes. The
astadr argument is the address of the entry mask of this routine.
astprm
VMS Usage: user_arg
type: longword (unsigned)
access: read only
mechanism: by value
AST parameter to be passed to the AST service routine specified
by the astadr argument. The astprm argument is this longword
parameter.
$SNDJBCW
The Send to Job Controller and Wait for Completion and $GETQUI
services together provide the user interface to the Job Controller
(JBC) facility. The $SNDJBW service allows you to create, stop,
and manage queues and the jobs in those queues. Queues can be
generic, batch, execution, or output queues. Jobs can be batch or
print jobs.
The $SNDJBCW service queues a request to the Job Controller. For
most operations, $SNDJBCW completes synchronously; that is, it
returns to the caller after the operation completes. However, if
the requested operation is a pause queue, stop queue, or abort
job operation, $SNDJBCW returns to the caller after queuing
the request. There is no way to synchronize completion of these
operations. Also, $SNDJBCW does not wait for a job to complete
before it returns to the caller. To synchronize completion of a
job, the caller must specify the SJC$_SYNCHRONIZE_JOB function
code.
The $SNDJBCW service is identical to the Send to Job Controller
($SNDJBC) service except that $SNDJBC completes asynchronously;
the $SNDJBC service returns to the caller immediately after
queuing the request, without waiting for the operation to
complete.
The $SNDJBC and $SNDJBCW services supersede the Send Message to
Symbiont Manager ($SNDSMB) and Send Message to Accounting Manager
($SNDACC) services. You should write new programs using $SNDJBC or
$SNDJBCW, instead of $SNDSMB or $SNDACC. You should convert old
programs using $SNDSMB or $SNDACC to use $SNDJBC or $SNDJBCW, as
convenient.
Format
SYS$SNDJBCW [efn] ,func [,nullarg] [,itmlst] [,iosb] [,astadr]
[,astprm]
$START_TRANS
Starts a transaction by allocating a transaction identifier
(TID) and establishing the internal structures that define a
transaction.
Format
SYS$START_TRANS [efn] ,[ flags] ,iosb [,[astadr] ,[astprm]
,[tid] ,[timout] ,[acmode]]
Arguments
efn
VMS Usage: ef_number
type: longword (unsigned)
access: read only
mechanism: by value
Number of the event flag to be set. The efn argument is a longword
containing this number; however, $START_TRANS uses only the low-
order byte. If you do not specify efn, $START_TRANS uses the
default value 0.
flags
VMS Usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by value
Flags specifying options for $START_TRANS. The flags argument is a
longword bit mask that is the logical OR of each bit set, in which
each bit corresponds to an option.
Table 1 $START_TRANS Option Flags
Flag Description
DDTM$M_ Indicates that this transaction is not the
NONDEFAULT process default transaction.
DDTM$M_SYNC Indicates successful synchronous completion by
returning SS$_SYNCH. When synchronous completion
is successful, the completion AST address is not
called, the IOSB is not written, and the event
flag is not set.
DDTM$M_PROCESS Indicates that the transaction might survive
image rundown. Caller must be in supervisor,
executive, or kernel mode.
iosb
VMS Usage: io_status_block
type: quadword (unsigned)
access: write only
mechanism: by reference
I/O status block (IOSB) to receive the final completion status of
the request. The iosb argument is the address of the quadword I/O
status block.
astadr
VMS Usage: ast_procedure
type: procedure entry mask
access: call without stack unwinding
mechanism: by reference
AST service routine to be executed. The astadr argument is the
address of the entry mask of this routine.
astprm
VMS Usage: user_arg
type: longword (unsigned)
access: read only
mechanism: by value
AST parameter passed to the AST service routine specified by the
astadr argument. The astprm argument is a longword.
tid
VMS Usage: transaction_id
type: octaword (unsigned)
access: write only
mechanism: by reference
Pointer to the transaction identifier (TID).
timout
VMS Usage: date_time
type: quadword (unsigned)
access: read only
mechanism: by reference
The time at which the transaction should be aborted if it has not
yet committed. A positive time value specifies an absolute time;
a negative time value specifies an offset (delta time) from the
current time.
acmode
VMS Usage: access_mode
type: longword (unsigned)
access: read only
mechanism: by value
The least privileged access mode that can end the transaction
using $END_TRANS. The acmode defaults to the caller's mode and is
maximized against it.
$START_TRANSW
Starts a transaction. It allocates a transaction identifier and
establishes the internal structures that define a transaction.
$START_TRANSW completes synchronously; that is, it returns to the
caller after the request has completed.
For asynchronous completion, you use the Start Transaction
($START_TRANS) service; $START_TRANS returns without waiting for
the operation to complete.
In all other respects, $START_TRANSW is identical to $START_TRANS.
For all other information about the $START_TRANSW service, refer
to the section on $START_TRANS.
Format
SYS$START_TRANSW [efn] ,[flags] ,iosb [,[astadr] ,[astprm]
,[tid] ,[timout] ,[acmode]]
V55 NewFeatures
VMS Version 5.5 includes new and changed features affecting general user, system management and programming components. This is a brief overview of VMS Version 5.5 software features. For additional information, see the VMS Version 5.5 New Features Manual or the online Help for specific commands or facilities.
Additional information available:
DCL CommandsLexical FunctionsBatch and Print Queuing System
System MessagesLADCP UtilityClusterwide Tape ServingVolume Shadowing Phase II
LAT SoftwareLicense Management FacilityQIO Support for Moving Disk Files
System ServicesRTL RoutinesDebuggerVMS DECthreads
DECdtmI/O DriversCase-Sensitive Language SupportSystem Dump Analyzer (SDA)
New VMS Documentation
DCL Commands
New DCL command qualifiers and options support the following
functions:
o Specify the size of DECram virtual disks (INITIALIZE/SIZE)
o The option of forcing an improperly dismounted disk volume to
be rebuilt to obtain the correct free block count (SET
VOLUME/REBUILD[=FORCE])
o Maintain the integrity of TZK10 tape cartridges by retensioning
the tape during rewinding or unloading (SET MAGTAPE/RETENSION)
o Create a file to log messages during CDA conversion operations
(CONVERT/DOCUMENT/MESSAGE_FILE)
Other new DCL command qualifiers and options support related
Version 5.5 new features including:
o Batch and print queuing system:
- DISABLE AUTOSTART
- ENABLE AUTOSTART
- INITIALIZE/QUEUE/AUTOSTART_ON=(node-list)
- PRINT/RETAIN
- SET ENTRY/RETAIN
- SET PREFIX
- SHOW ENTRY
- SHOW QUEUE
- START/QUEUE/AUTOSTART_ON=(node-list)
- START/QUEUE/MANAGER
- STOP/QUEUE/MANAGER/CLUSTER
- STOP/QUEUE/NEXT
- STOP/QUEUE/RESET
- STOP/QUEUES/ON_NODE
- SUBMIT/NOTE
- SUBMIT/RETAIN
o License Management Facility
- LICENSE COPY
- LICENSE ISSUE/PROCEDURE
- LICENSE MODIFY/RESERVE
- LICENSE MOVE
- LICENSE subcommand/ALL
o MACRO Support for Case Sensitivity
- MACRO/NAMES
o Disk Management
- SET FILE/NOMOVE[MOVE]
o Local Area Transport (LAT) Enhancements
- SET HOST/LAT
o Asynchronous Printer Support
- SET TERMINAL/COMMSYNC
See appropriate New Features Help for more information about these
other DCL commands.
Lexical Functions
The F$MESSAGE lexical function has been modified to let you specify the system message component for which information is to be returned. For the new batch and print queuing system, the F$ENVIRONMENT lexical function has a new item, VERIFY_PREFIX, which returns the prefix control string for verified command lines. The F$GETQI lexical function returns information about the AUTOSTART feature and about user-specified job retention.
Batch and Print Queuing System
The VMS Version 5.5 batch and print queuing system provides the following improvements over the previous queuing system: o Improved reliability and availability of batch and print queues o Improved performance in large configurations o Greater emphasis on clusterwide operation
Additional information available:
General User FeaturesSystem Management FeaturesProgramming Features
General User Features
Additional information available:
SHOW ENTRY DisplayJob Name Parameter for SHOW ENTRY CommandStalled Job State
SHOW QUEUE DisplayUser-Specified Job RetentionBatch Log Time Stamps
F$GETQUI Lexical Function Changes
/NOTE_Qualifier_for_SUBMIT_Command
SHOW ENTRY Display
In the new batch and print queuing system, the format for the SHOW
ENTRY display is changed and appears similar to the following:
Entry Jobname Username Blocks Status
----- ------- -------- ------ ------
6 MYJOB HERSHEY Retained on completion
On stopped generic batch queue CLUSTER_BATCH
Completed 28-MAR-1991 17:52 on queue NODE_BATCH
The new display makes it easier for a user to locate a job's entry
number. This is important because the entry number is needed for
the SET ENTRY and DELETE/ENTRY commands. The new display also
includes the state of the queue in which the job is currently
located.
Job Name Parameter for SHOW ENTRY Command
The SHOW ENTRY command now accepts a job name as a legal value for its parameter. The command SHOW ENTRY job_name displays all of the user's jobs having the specified job name. For more information see the SHOW ENTRY command.
Stalled Job State
When the physical device to which a queue is assigned is stalled,
the job's status now appears as "Stalled" as shown in the
following example:
Entry Jobname Username Blocks Status
----- ------- -------- ------ ------
6 MYJOB HERSHEY 238 Stalled
On stalled printer queue NODEA_PRINT
The new display also includes the state of the queue in which the
job is located.
SHOW QUEUE Display
The display for the SHOW QUEUE command is changed to appear
similar to the following:
Batch queue NODE_BATCH, busy, on NODE22::
Entry Jobname Username Status
----- ------- -------- ------
6 SET HERSHEY Executing
The new display makes it easier for you to locate a job's entry
number.
User-Specified Job Retention
The /RETAIN qualifier can be used with the PRINT, SUBMIT, or SET
ENTRY command to specify the circumstances under which you want
a job to be retained in a queue after the job completes. For more
information, see the /RETAIN qualifier for the DCL command PRINT,
SUBMIT, or SET ENTRY.
Specifying job retention can be useful for the following reasons:
o Changes to the SHOW ENTRY and SHOW QUEUE displays include the
date and time at which a retained job completed and the queue
on which it executed. This information can help you determine
to which printer a print job's output was sent.
o As with previous versions, the SHOW ENTRY and SHOW QUEUE
displays for jobs retained on error also include the
unsuccessful status message. This message can help you
determine why a job did not complete sucessfully.
Without job retention, no record of a job is left in a queue after
a job completes. However, when a job is retained in the queue, you
can issue the SHOW QUEUE command after the job completes to see
the status of the job.
Timed retention, which you specify using the UNTIL=time-value
option, allows you to retain a job in the queue only as long as
you need it. This eliminates the need to delete the job from the
queue later.
Batch Log Time Stamps
Batch log time stamps let you time-stamp your batch log files using a full date and time prefix to identify batch runs and to verify that a batch job ran at the expected time. The SET PREFIX command lets you specify a control string to be used to prefix verified command lines. If procedure verification is in effect, then the control string will generate a prefix to which the verified line is appended. For more information see the DCL command SET PREFIX. A new item, VERIFY_PREFIX, has been added to the F$ENVIRONMENT lexical function to return the prefix control string for verified command lines. For more information, see the F$GETQUI lexical function.
/NOTE_Qualifier_for_SUBMIT_Command
The SUBMIT command accepts the /NOTE qualifier. This qualifier lets you specify a message string to appear as part of the display on a SHOW QUEUE/FULL command and can thus be used to convey information concerning the job. The message specified with the /NOTE qualifier is also printed on the flag page of the log file and can be used to convey post-printing information.
F$GETQUI Lexical Function Changes
The F$GETQUI lexical function is enhanced as follows:
o to return information about the autostart feature.
o to return information about user-specified job retention.
o to accept a job name in the object-id argument to the DISPLAY_
ENTRY function code.
For more information, see the F$GETQUI lexical function.
System Management Features
Additional information available:
Clusterwide Queue ManagerNew Design for the Queue DatabaseStarting and Stopping the Queue Manager
The Autostart Feature
Clusterwide Queue Manager
The VMS Version 5.5 queuing system includes a new queue manager. A single queue manager process now acts as a clusterwide server, accessing the queue database for all processes in a cluster. Queue manager and job controller functions are now separate. The new centralized design reduces disk activity associated with the distributed design. It also enables the queue manager to fail over to another node if the node on which it is running leaves the cluster. For more information, see the Guide to Maintaining a VMS System.
New Design for the Queue Database
The file previously used as the queue database, JBCSYSQUE.DAT, is
no longer used. The new queue database consists of the following
new files:
QMAN$MASTER.DAT, the master file
SYS$QUEUE_MANAGER.QMAN$QUEUES, the queue file
SYS$QUEUE_MANAGER.QMAN$JOURNAL, the journal file
SYS$COMMON:[SYSEXE] is the default location for all three queue
database files. However, you can move the files to another
location. For more information, see the Guide to Maintaining a
VMS System.
Starting and Stopping the Queue Manager
Changes in the batch and print queuing system affect the command
used to start and stop the queue manager. The following commands
are new or changed:
Command Change
START/QUEUE/MANAGER Change in behavior. Qualifiers
/BUFFER_COUNT, /EXTEND, and /RESTART
are obsolete. New dirspec parameter.
STOP/QUEUE/MANAGER/CLUSTER Replaces the obsolete command STOP
/QUEUE/MANAGER.
STOP/QUEUES/ON_NODE New command.
For more information, see the Help for these commands, and the
Guide to Maintaining a VMS System.
The Autostart Feature
The autostart feature simplifies startup of queues and ensures
high availability of execution queues in a cluster. An autostart
queue is a special type of execution queue that makes use of
the autostart feature. The autostart feature lets you do the
following:
o Start all autostart queues on a node with a single command
o Specify a list of nodes (within a VAXcluster environment) to
which a queue can automatically fail over if a node is removed
from the cluster
For these reasons, Digital recommends that you use autostart
queues whenever possible.
The following DCL commands are new or changed to support the
autostart feature:
Command Change
INITIALIZE/QUEUE new /AUTOSTART_ON qualifier
START/QUEUE new /AUTOSTART_ON qualifier
ENABLE AUTOSTART/QUEUES new command
DISABLE AUTOSTART/QUEUES new command
For more information, see the Help for these commands and the Guide
to Maintaining a VMS System.
Additional information available:
Enabling Autostart on a NodeStarting Autostart QueuesPreventing Autostart Queues from Starting
Disabling Autostart on a Node
Enabling Autostart on a Node
The command ENABLE AUTOSTART/QUEUES enables autostart on a node. For more information, see the Help for this command, and the Guide to Maintaining a VMS System.
Starting Autostart Queues
You must start an autostart queue initially, in one of the
following ways:
o Specify the /START qualifier in the INITIALIZE/QUEUE command
used to create the queue.
o Enter a START/QUEUE command after you create the queue.
Autostart must be enabled on the node for the queue to begin
executing jobs. Once autostart is enabled and the queue is started
initially, the queue will remain started until either of the
following occurs:
o Autostart is disabled on the node with the DISABLE AUTOSTART or
STOP/QUEUES/ON_NODE command or if the node leaves the cluster.
o The queue is stopped with a STOP/QUEUE/NEXT or STOP/QUEUE/RESET
command.
For more information, see the Guide to Maintaining a VMS System.
Preventing Autostart Queues from Starting
With autostart queues, the STOP/QUEUE/NEXT or STOP/QUEUE/RESET command stops a queue and marks it inactive for autostart until the START/QUEUE command is entered. The STOP/QUEUE/NEXT or STOP /QUEUE/RESET command prevents an autostart queue from being automatically restarted. You might use this feature to prevent an autostart output queue from accidentally restarting when a printer is being serviced.
Disabling Autostart on a Node
The DISABLE AUTOSTART/QUEUES command disables autostart on a node. For more information, see the Help for this command, and the Guide to Maintaining a VMS System.
Programming Features
Additional information available:
$GETQUI Service$SNDJBC ServiceLIB$GETQUI Run-time Library Routine
$GETQUI Service
The $GETQUI system service is enhanced to support the new queuing
system features. Enhancements include the following (for more
information, see the VMS System Services Reference Manual):
Five new item codes:
QUI$_AUTOSTART_ON
QUI$_JOB_RETENTION_TIME
QUI$_JOB_COMPLETION_TIME
QUI$_JOB_COMPLETION_QUEUE
QUI$_SEARCH_JOB_NAME
Eight new bit codes:
QUI$V_JOB_RETENTION
QUI$V_JOB_ERROR_RETENTION
QUI$V_QUEUE_AVAILABLE
QUI$V_QUEUE_BUSY
QUI$V_QUEUE_STOP_PENDING
QUI$V_JOB_STALLED
QUI$V_QUEUE_AUTOSTART
QUI$V_QUEUE_AUTOSTART_INACTIVE
Designation of nine previously existing QUI$_QUEUE_STATUS bits as
state bits:
QUI$V_QUEUE_IDLE
QUI$V_QUEUE_DISABLED
QUI$V_QUEUE_PAUSED
QUI$V_QUEUE_PAUSING
QUI$V_QUEUE_RESUMING
QUI$V_QUEUE_STALLED
QUI$V_QUEUE_STARTING
QUI$V_QUEUE_STOPPED
QUI$V_QUEUE_STOPPING
$SNDJBC Service
The $SNDJBC system service is enhanced to support the new queuing
system features. Enhancements include the following (for more
information, see the VMS System Services Reference Manual):
Three new function codes:
SJC$_STOP_ALL_QUEUES_ON_NODE
SJC$_ENABLE_AUTOSTART
SJC$_DISABLE_AUTOSTART
Seven new item codes:
SJC$_QUEUE_MANAGER_NODES
SJC$_QUEUE_DIRECTORY
SJC$_AUTOSTART_ON
SJC$_JOB_RETAIN
SJC$_JOB_ERROR_RETAIN
SJC$_JOB_DEFAULT_RETAIN
SJC$_JOB_RETAIN_TIME
Extended use of one item code:
SJC$_SCSNODE_NAME
LIB$GETQUI Run-time Library Routine
The changes to the $GETQUI system service affect the LIB$GETQUI run-time library routine. For more information, see $GETQUI Service.
System Messages
This version of VMS includes a number of new, updated, or previously undocumented system messages for various VMS facilities. Type HELP ERROR at the DCL prompt to get help information for any message.
LADCP Utility
This utility permits you to configure and control the local area disk (LAD) protocol on VMS host systems. See the VMS LAD Control Program (LADCP) Manual for more information about the LADCP utility.
Clusterwide Tape Serving
Users on a node in a cluster can now access magnetic tape devices physically connected to any other node in the cluster through the implementation of a tape mass storage control protocol (TMSCP).
Volume Shadowing Phase II
Phase II supports a new SYSGEN parameter (SHADOW_MBR_TMO) that lets you specify the timeout period for recovering a shadow set member before it is removed from a shadow set. Phase II also provides support for SCSI devices.
LAT Software
You can now use the SET HOST/LAT command to establish outbound (forward) LAT connections. New LATCP commands permit you to display information about various LAT entities and there is a new startup procedure for LAT software. The LAT SETMODE $QIO function is used to create and delete LAT entities such as nodes, services, ports, and links. It is also used to modify parameters of these entities. The LAT SENSEMODE $QIO function is used to obtain information about LAT entities, including nodes, services, ports, and links.
License Management Facility
LMF has been enhanced to allow the transfer of licenses between databases and the registration of a license in another license database. System managers or privileged users can now attach a list of names to product licenses and software vendors can issue PAKs with the RESERVE_UNITS option. Another enhancement allows license managers to perform operations on groups of licenses.
QIO Support for Moving Disk Files
Three DCL commands, SET FILE, DIR/FULL and DUMP/HEADER, have been enhanced to support movefile operations that enable you to move all or part of the contents of a file to a new disk location. Typically, this might be used as part of a disk defragmentation application.
Additional information available:
Movefile Command QualifiersCalling the Movefile Subfunction
Movefile Command Qualifiers
This topic describes the DCL commands that have been enhanced to
support movefile operations:
o The SET FILE command -- new qualifiers allow you to disable and
reenable movefile operations.
o The DIRECTORY/FULL command, and the DUMP/HEADER and
DUMP/FILE_HEADER commands -- these now also indicate when
movefile operations are disabled.
A movefile operation moves the contents of a file, or part of the
contents of a file, to a new disk location. Movefile operations
are only performed by specialized applications, such as disk
defragmentation applications.
Additional information available:
DIRECTORY CommandDUMP Commands
SET_FILE
The new SET FILE qualifiers, /NOMOVE and /MOVE, control whether
movefile operations can be performed on the specified file (or
files).
Format
SET FILE/[NO]MOVE file-spec[,...]
When you create a file, movefile operations are enabled on that
file. To disable movefile operations, use the /NOMOVE qualifier.
You should disable movefile operations on specialized files that
are accessed other than through the XQP (such as files accessed
through logical I/O to the disk).
To reenable movefile operations on a file, use the /MOVE
qualifier.
NOTE
Movefile operations are automatically disabled on critical system
files. Do not enable movefile operations on these files.
For a list of critical system files, see the VMS Version 5.5 New
Features Manual.
Additional information available:
Example
$SET FILE/NOMOVE TEST.FDL
$DIRECTORY/FULL TEST.FDL
Directory SYS$SYSDEVICE:[SMITH]
TEST.FDL;1 File ID: (10,8,0)
.
.
.
File attributes: Allocation: s, Extend: 0, Global buffer count: 0
No version limit, MoveFile disabled
.
.
.
In this example, movefile operations are disabled on the file
TEST.FDL. A DIRECTORY/FULL command on the file TEST.FDL affirms
that the file attribute MoveFile is disabled.
DIRECTORY Command
The DIRECTORY/FULL command now also indicates when movefile operations are disabled on a file.
Additional information available:
Example
$ DIRECTORY/FULL TEST.FDL
Directory SYS$SYSDEVICE:[SMITH]
TEST.FDL;1 File ID: (10,8,0)
.
.
.
File attributes: Allocation: s, Extend: 0, Global buffer count: 0
No version limit, MoveFile disabled
.
.
.
In this example, a DIRECTORY/FULL operation on the file TEST.FDL
shows that movefile operations are disabled.
DUMP Commands
The DUMP/HEADER and DUMP/FILE_HEADER commands now also indicate when movefile operations are disabled on a file.
Additional information available:
Example
$ DUMP/HEADER TEST.FDL
Dump of file SYS$SYSDEVICE:[SMITH]TEST.FDL;1 on 1-MAY-1991 17:19:41.76
File IOD (8,10,0) End of file block 2 / Allocated 3
File Header
Header area
.
.
.
File characteristics: MoveFile disabled
.
.
.
In this example, a DUMP/HEADER operation on the file TEST.FDL shows
that movefile operations are disabled.
Calling the Movefile Subfunction
A program can invoke a movefile subfunction by issuing a QIO request using the function code IO$_MODIFY and the function modifier IO$M_MOVEFILE. This topic describes the input parameters that control the processing of movefile operations and also how the movefile subfunction works.
Additional information available:
Input Parameters
This topic describes the FIB (file identification block) fields that control the processing of a movefile operation.
Additional information available:
FIB$L_ACCTLFIB$W_FIDFIB$W_EXCTLFIB$B_ALOPTS
FIB$B_ALALIGNFIB$W_ALLOCFIB$L_MOV_SVBNFIB$L_MOV_VBNCNT
FIB$L_ACCTL
Control flags. The following flag applies to the movefile
operation.
Field Value Meaning
FIB$V_NOVERIFY Inhibits comparison of the moved blocks. If this
flag is clear, the movefile operation verifies
that the operation was carried out correctly
by comparing the moved blocks to the original
blocks.
FIB$W_FID
Specifies the file identification of the file to be moved.
FIB$W_EXCTL
Movefile control flags. The following flags apply to the movefile
operation. All other FIB$W_EXCTL flags must be clear.
Field Value Meaning
FIB$M_ALCON Specifies that the movefile operation must
allocate contiguous disk space to the moved
blocks. If the necessary contiguous space is
not available, the movefile operation fails.
The movefile operation sets this flag if the file
was previously marked contiguous.
FIB$M_ALCONB Specifies that the movefile operation should do
its best to allocate contiguous disk space to the
moved blocks. That is, if the movefile operation
cannot allocate contigous space to all the moved
blocks, it allocates contiguous space to as many
of the blocks as possible.
The movefile operation sets this flag if the file
was previously marked contiguous best try.
FIB$M_FILCON Specifies that the entire file must be made
contiguous. Do not set this flag without also
setting the FIB$M_ALCON flag.
If the FIB$M_FILCON flag is set, and either
the FIB$M_ALCON flag is clear or the file would
not be made contiguous by moving the specified
virtual blocks, the movefile operation fails.
The movefile operation sets this flag if the file
was previously marked contiguous.
FIB$V_NOPLACE Specifies that placement information will not be
recorded in the file header.
If this flag is clear, and you specify exact
placement for the moved blocks, placement
information for those blocks will be recorded
in the file header. If this flag is set, the
placement information will not be recorded.
You specify exact placement through the
FIB$M_EXACT, FIB$C_LBN, and FIB$L_LOC_ADDR
fields.
FIB$B_ALOPTS
Flags that control the placement of the allocated blocks.
Currently, only the FIB$M_EXACT flag applies to the movefile
operation. All other FIB$B_ALOPTS flags must be clear.
Field Value Meaning
FIB$M_EXACT Set to require exact placement. If this flag is
set and the specified blocks are not available,
the movefile operation fails.
FIB$B_ALALIGN
Contains the interpretation mode of the allocation field (FIB$W_
ALLOC). You can specify a field value of zero or you can specify
the symbolic value FIB$C_LBN. If you specify zero, the allocation
field is ignored.
Field Value Meaning
FIB$C_LBN If the FIB$M_EXACT flag is also set, indicates
that the FIB$L_LOC_ADDR subfield contains the
starting logical address to which the blocks are
moved.
FIB$W_ALLOC
Contains the desired location of the blocks being allocated.
Interpretation of the field is controlled by the FIB$B_ALALIGN
field.
Field Value Meaning
FIB$B_LOC_RVN Placement relative volume number (RVN).
FIB$L_LOC_ADDR If the FIB$C_LBN and FIB$M_EXACT flags are set,
specifies the starting logical address to which
the blocks are moved.
FIB$L_MOV_SVBN
Specifies the virtual block number (VBN) of the first block to be moved. The starting virtual block number must correspond to the first block of a disk cluster. The value must be greater than zero and it must not exceed the number of virtual blocks allocated to the file. If you specify an invalid value, the movefile operation fails.
FIB$L_MOV_VBNCNT
Specifies the number of consecutive virtual blocks to be moved. This value must be a multiple of the disk cluster size and it must not exceed the difference between the greatest VBN (virtual block number) allocated to the file and the FIB$L_MOV_SVBN value. If you specify a value of zero, the movefile operation moves all the virtual blocks between the FIB$L_MOV_SVBN value and the greatest VBN. If you specify an invalid value, the movefile operation fails.
Operation
A program can perform a movefile operation on a file if the
following conditions are met:
o The program has write and control access to the file.
o The file is closed.
o Movefile operations are not disabled on the file.
Movefile operations are automatically disabled on critical
system files. You can disable movefile operations on specific
user files by specifying the /NOMOVE qualifier on the SET FILE
command. See <REFERENCE>(Movefile_DCL_Support).
o The operation is not interrupted.
If the movefile operation is interrupted by any other
operation, the movefile operation aborts and the file remains
in its original position.
o The source and target locations are on the same disk.
You cannot transfer blocks from one volume to another and you
cannot move blocks spanning more than one volume.
The movefile operation moves a specified number of consecutive
virtual blocks to new logical blocks on the disk, beginning with
the virtual block specified in the FIB$L_SVBN field.
The number of blocks moved is specified in the FIB$L_VBNCNT field.
To move an entire file, specify FIB$L_VBNCNT as 0 and FIB$L_SVBN
as 1.
To specify a starting logical block number for the moved blocks,
write the logical block address in the FIB$L_LOC_ADDR subfield and
set the FIB$C_LBN and the FIB$M_EXACT flags.
If the file was previously marked contiguous, the movefile
operation sets the FIB$M_ALCON and FIB$M_FILCON flags. This
ensures that a contiguous file is not fragmented by a movefile
operation. Similarly, if the file was previously marked contiguous
best try, the movefile operation sets the FIB$M_ALCONB flag.
For virtual blocks beyond the file's highwater mark, the movefile
operation allocates new logical blocks but does not copy the
contents. The position of the file's highwater mark remains
unchanged.
System Services
The $GETQUI and $SNDJBC system services have been modified to support the batch and print queuing system and to provide additional support for the LIB$GETQUI run-time library routine. For more information, see the New Features Help about the batch and print queuing system. System services have also been modified to support new DECdtm features.
RTL Routines
The fast-vector math routines provide alternative math functions that offer significantly higher performance. LIB$GETQUI has been enhanced to support the new batch and print queuing system. The PPL$ run-time library provides enhanced unique naming functionality and spin/wait options for several blocking synchronization routines.
Debugger
For VMS Version 5.5, the VMS Debugger provides enhanced support
for tasking programs. Tasking programs (also called multithread
programs) have multiple threads of execution within a VMS process.
Ada programs have built-in tasking services, and debugger support
for VAX Ada tasking programs has been available since VMS Version
4.2 (since VAX Ada Version 1.0).
Starting with VMS Version 5.5, debugger tasking support has been
extended to also include any program that uses DECthreads or
POSIX 1003.4a services. These services are provided for languages
that do not have built-in tasking services.
Debugger tasking support enables you to perform functions such as
the following:
o Display task information
o Modify task characteristics to control task execution, priority,
state transitions, and so on
o Monitor task-specific events and state transitions
Additional information available:
Command Interface EnhancementsDECwindows Interface Enhancements
Command Interface Enhancements
There are no new commands or qualifiers. However, the following
commands, which are task related, have been enhanced to provide the
new support:
o SET TASK, SHOW TASK
o SET EVENT_FACILITY (you can now specify THREADS, in addition to
ADA and SCAN, as a command parameter)
o SHOW EVENT_FACILITY
o SET BREAK/EVENT, SET TRACE/EVENT (THREADS events are now defined
in addition to ADA and SCAN events)
See the VMS Debugger Manual for complete information about these
commands and qualifiers.
DECwindows Interface Enhancements
There are no visible changes to the debugger's DECwindows interface. However, the tasking features that are available by choosing Tasks... from the Data menu in the main window have been enhanced to provide the new support. See the VMS Debugger Manual and online help that is available from the debugger's DECwindows interface for complete information about these features.
VMS DECthreads
Version 5.5 provides a Multithreading Run-Time Library, comprising a library of portable routines used for creating and controlling multiple threads of execution within the address space provided by a single process.
DECdtm
Version 1.1 of the DECdtm services provides transaction abort reason codes and you can set a time limit on transactions.
I/O Drivers
The terminal driver interface supports connection of an asynchronous printer to a terminal port using modem signals for flow control. The mailbox driver now waits until a channel with the requested access direction is assigned to the mailbox.
Additional information available:
Mailbox Driver
VMS Version 5.5 provides the following new mailbox driver features:
o Prior to VMS Version 5.5, channels assigned to mailboxes have
always been bidirectional (read/write) channels. This means
that both read requests and write requests can be issued to
the channel. Channels can now be assigned to mailboxes as
unidirectional, either read only or write only.
o The wait for writer/reader mailbox driver function. This function
waits until a channel is assigned to the mailbox with the
requested access direction.
o The IO$M_WRITERCHECK function modifier has been added for the read
mailbox function. This modifier completes the I/O operation, with
SS$_NOWRITER status, if the mailbox is empty and no write channels
are assigned to the mailbox.
o The IO$M_READERCHECK function modifier has been added for the
write and write end-of-file message mailbox function. This
modifier completes the I/O operation immediately, with SS$_
NOREADER status, if no read channels are assigned to the mailbox.
o The IO$M_STREAM function modifier has been added for the read
mailbox function. This modifier ignores QIO record boundaries,
and transfers message data to the user's buffer until either the
number of bytes specified by the P2 argument are transferred,
all message data currently in the mailbox is transferred, or an
end-of-file message is encountered.
Case-Sensitive Language Support
The VMS linker and the MACRO assembler now support case sensitivity. Case sensitivity is the capability to sense and act upon alphabetic input with regard to its being uppercase or lowercase. The linker preserves the mixture of upper and lowercase characters used in character-string arguments to linker options. MACRO now enables programmers to specify the case sensitivity of global symbol definitions.
Additional information available:
Linker Support for Case-Sensitive LanguagesVAX MACRO Support for Case Sensitivity
Linker Support for Case-Sensitive Languages
The VMS Linker Utility, with VMS Version 5.5, implements a new linker option, CASE_SENSITIVE=, that allows you to preserve the mixture of uppercase and lowercase characters used in character-string arguments to linker options. When this option is enabled, the linker interprets the symbols MySymbol and mysymbol as two distinct character strings. Once case sensitivity has been enabled, the linker preserves the case of all succeeding character-string arguments to linker options until you explicitly disable it. When the CASE_SENSITIVE= option is disabled (which is the default), the linker changes all the characters in a character string to uppercase before processing the string. To enable case sensitivity, specify the CASE_SENSITIVE= option with the value YES on a line in the options file. You can use any mixture of uppercase and lowercase characters in YES. To disable case sensitivity, specify the CASE_SENSITIVE= option with the value NO as its argument. Note that, because case sensitivity is enabled, you must use uppercase characters when specifying NO. Carefully delimit the section of a linker options file in which you use case sensitivity to avoid unintentional side effects. For example, if you include options in the case-sensitive region that accept values, such as YES, NO, EXE, and SHR, make sure the values are specified using uppercase characters. Because these values appear after the equal sign (=), they are affected by case sensitivity. Similarly, character-string arguments used to name a psect, cluster, or image are also affected by case sensitivity.
Additional information available:
Example
$ link/share/map/full test, sys$input:/opt
case_sensitive=YES
name=ImageName
symbol=OneSymbol,1
case_sensitive=NO
universal=myroutine
<Ctrl/z>
In this example, because case sensitivity is enabled, the linker
preserves the mix of uppercase and lowercase characters used in
the character-string argument ImageName, passed to the NAME= option,
and the character string argument OneSymbol, passed to the SYMBOL=
option. The linker changes all the characters in the character string
argument myroutine, passed to the UNIVERSAL= option, to uppercase
because case sensitivity is disabled.
The following excerpt from the map file produced
by this link command illustrates how these identifiers were
stored by the linker:
ImageName
OneSymbol
MYROUTINE
VAX MACRO Support for Case Sensitivity
This version of VAX MACRO enables programmers to specify the case
sensitivity of global symbol definitions. This is accomplished
using the new MACRO command line qualifier, /NAMES.
{ UPPER } ! Symbol definitions in uppercase (default)
$ MACRO/NAMES={ DEFINITIONS:LOWER } ! Symbol definitions in lowercase
{ DEFINITIONS:UPPER } ! Symbol definitions in uppercase
{ DEFINITIONS:BOTH } ! Symbol definitions in both
! uppercase and lowercase
The /NAMES qualifier enables you to observe case sensitivity when
referencing MACRO routines in languages that generate references
in lowercase.
/NAMES=UPPER specifies that all global symbol definitions are
converted and generated in all lowercase characters. This is the
default case and is consistent with the behavior of the current
product.
If you specify /NAMES=DEFINITION:LOWER, then all global symbol
definitions are converted and generated in all lowercase
characters. If you specify /NAMES=DEFINITION:UPPER, then all
global symbol definitions are converted and generated in all
uppercase characters. There is no mixed casing or the ability
to select which symbols within a module are generated in uppercase
and which are generated in lowercase.
The /NAMES=DEFINITION:BOTH option generates the symbol definitions
in both uppercase and lowercase.
This is a positional qualifier; therefore, you can specify which
modules are affected by the qualifier.
Only the global symbol definitions are generated in the specified
case sensitivity. The generation of requests, that is, calls or
jumps to subroutines (JSBs), remain unchanged (uppercase).
Additional information available:
ExamplesMACRO Programs That Reference Other MACRO ModulesMACRO Programs That Reference the Same MACRO Module
Uppercase Languages to MACRO ProgramsLowercase Languages to MACRO Programs
MACRO Command /NAMES Qualifier
Examples
1. $MACRO/NAMES=DEFINITIONS:UPPER TEST.MAR In this example, global symbol definitions from TEST.MAR are produced in the resulting object file (TEST.OBJ) in uppercase. 2. $MACRO TEST.MAR/NAMES=UPPER, TEST2.MAR/NAMES=DEFINITION:LOWER In this example, global symbol definitions from TEST.MAR are produced in the resulting object file (TEST.OBJ) in uppercase and global symbol definitions from TEST2.MAR are produced in the resulting object file (TEST2.OBJ) in lowercase. Sections 1.2 through 1.8 describe how the /NAMES qualifier functions in different environments.
MACRO Programs That Reference Other MACRO Modules
A MACRO program can reference global symbols only in other MACRO
modules that have been assembled using either the UPPER or BOTH
case-sensitivity value. This also implies that modules that define
transfer vectors and are referenced by separate MACRO modules
follow this rule.
In the following table, the transfer vector module consists of
transfer vector definitions only. The caller modules are assembled
using the UPPER case-sensitivity value.
Called Routine
Caller (In Separate Module)
MACRO MACRO
MACRO Transfer Vector
MACRO Programs That Reference the Same MACRO Module
MACRO routines that reference global symbols that are defined in
the same module, but cross program sections, must be assembled
using either the UPPER or BOTH case-sensitivity value. This means
that a module consisting of both transfer vector definitions and
code in independent PSECTs follow the same rule.
In the following table, the MACRO module contains both the caller
and called routine, but they reside in separate PSECTs. These
modules must be assembled using either the UPPER or BOTH case-
sensitivity value.
Called Routine
Caller (In Same Module)
MACRO MACRO
Transfer Vector MACRO
Uppercase Languages to MACRO Programs
MACRO modules that define transfer vectors must be assembled
using either the UPPER or BOTH case-sensitivity value when used by
MACRO or any other uppercase language. This imposes the same case
sensitivity on the called routine.
Caller Transfer Module Called Routine
MACRO or MACRO/UPPER MACRO/UPPER or BOTH
any other
uppercase
language
MACRO/BOTH MACRO/BOTH (required)
MACRO/UPPER Any mixed-case language, for
example, C. Routine name must be in
uppercase.
Lowercase Languages to MACRO Programs
Languages other then MACRO can use MACRO transfer vectors by
means of a LOWER request (as long as they support generating
lowercase requests). This requires that the MACRO module that
contains the transfer directive definitions must be assembled
using the BOTH case-sensitivity value. If the routine is in
MACRO, then this module must also be assembled using the BOTH
case-sensitivity value. Other languages that are referenced by
the transfer vector must generate the symbol definition in both
uppercase and lowercase. This is necessary to allow the linker the
ability to resolve the symbolic references.
Caller Transfer Module Called Routine
Lowercase MACRO/BOTH MACRO/BOTH
call
MACRO/BOTH Any mixed-case language, for
example, C. Symbol definition name
must be generated in uppercase and
lowercase.
MACRO Command /NAMES Qualifier
This section describes the /NAMES qualifier for the MACRO command.
/NAMES
Allows you to specify the case sensitivity of global symbol
definitions.
Format
MACRO filespec[,...]
Description
Starting with VMS Version 5.5, the DCL command MACRO accepts a
new qualifier, /NAMES. The /NAMES qualifier enables you to observe
case sensitivity when referencing MACRO routines in languages that
generate references in lowercase.
/NAMES=UPPER specifies that all global symbol definitions are
converted and generated in all lowercase characters. This is the
default case and is consistent with the behavior of the current
product.
If you specify /NAMES=DEFINITION:LOWER, then all global symbol
definitions are converted and generated in all lowercase
characters. If you specify /NAMES=DEFINITION:UPPER, then all
global symbol definitions are converted and generated in all
uppercase characters. There is no mixed casing or the ability
to select which symbols within a module are generated in uppercase
and which are generated in lowercase.
The /NAMES=DEFINITION:BOTH option generates the symbol definitions
in both uppercase and lowercase.
This is a positional qualifier; therefore, you can specify which
modules are affected by the qualifier.
Only the global symbol definitions are generated in the specified
case sensitivity. The generation of requests, that is, calls or
jumps to subroutines (JSBs), remain unchanged (uppercase).
Examples
1. $MACRO/NAMES=DEFINITION:UPPER TEST.MAR
In this example, global symbol definitions from TEST.MAR are
produced in the resulting object file (TEST.OBJ) in uppercase.
2. $MACRO TEST.MAR/NAMES=DEFINITION:UPPER, TEST2.MAR/NAMES=DEFINITION:LOWER
In this example, global symbol definitions from TEST.MAR are
produced in the resulting object file (TEST.OBJ) in uppercase
and global symbol definitions from TEST2.MAR are produced in
the resulting object file (TEST2.OBJ) in lowercase.
System Dump Analyzer (SDA)
The following additions have been made to the System Dump Analyzer
for VMS Version 5.5:
o The SDA symbol table now includes the symbol TMSCP. TMSCP
represents the address of loadable TMSCP server code.
o The commands SHOW LOGS and SHOW TRANSACTIONS have been added, to
support transaction processing. SHOW LOGS displays information
about transaction log files on the node. SHOW TRANSACTIONS
displays information about transactions on the node.
o The /PARTICIPANTS and /TRANSACTIONS qualifiers have been added
to the SHOW PROCESS command. SHOW PROCESS /PARTICIPANTS specifies
the type of information about transaction participant control
structures to be displayed. SHOW PROCESS /TRANSACTIONS specifies
the transaction related structure information to be displayed for
the selected or current process.
New VMS Documentation
The VMS Version 5.5 documentation set includes a new handbook entitled Building Dependable System and a new manual, Using VMS BACKUP, is available to help users complete common tasks with the VMS Backup Utility (BACKUP).