HELP — VMS 5.4
Additional information available:
:==@ACCOUNTINGALLOCATEANALYZE
APPENDASSIGNATTACHAUTHORIZEAUTOGENBACKUP
CALLCANCELCLOSECONNECTCONTINUECONVERTCOPY
CREATEDEALLOCATEDEASSIGNDEBUGDECKDEFINE
DELETEDEPOSITDIFFERENCESDIRECTORYDISCONNECT
DISKQUOTADISMOUNTDUMPEDITEODEOJ
EXAMINEEXCHANGEEXITFDLFONTGOSUBGOTO
HELPIFINITIALIZEINQUIREINSTALLJOBLATCP
LIBRARYLICENSELINKLMCPLOGINLOGOUTMACRO
MAILMERGEMESSAGEMONITORMOUNTNCPNCS
ONOPENPASSWORDPATCHPHONEPRINTPSWRAP
PURGEREADRECALLRECOVERRENAMEREPLYREQUEST
RETURNRMSRUNRUNOFFSEARCHSETSHOW
SORTSPAWNSTARTSTOPSUBMITSYNCHRONIZE
SYSGENSYSMANTFFTYPEUILUNLOCKVIEW
WAITWRITE
Format of errorHintsInstructionsLexicalsLine editingQueues
RTL RoutinesSpecifySymbol AssignSystem Services
V54 NewFeatures
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. PROCEDURE returns
a null string if used interactively.
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_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 SYSPRV (system privilege) 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]
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 flags
values 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$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]
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.
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]
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.
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
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.
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_RU$ABORT_TRANS$ABORT_TRANSW$ADD_HOLDER
$ADD_IDENT$ADJSTK$ADJWSL$ALLOC$ASCEFC$ASCTIM
$ASCTOID$ASSIGN$BINTIM$BRKTHRU$BRKTHRUW$CANCEL
$CANEXH$CANTIM$CANWAK$CHANGE_ACL$CHECK_ACCESS
$CHKPRO$CLREF$CMEXEC$CMKRNL$CNTREG$COMMIT_RU
$CRELNM$CRELNT$CREMBX$CREPRC$CREATE_RDB$CRETVA
$CRMPSC$DACEFC$DALLOC$DASSGN$DCLAST$DCLCMH$DCLEXH
$DELLNM$DELMBX$DELPRC$DELTVA$DEQ$DEVICE_SCAN
$DGBLSC$DISMOU$DLCEFC$DNS$DNSW$END_RU$END_TRANS
$END_TRANSW$ENQ$ENQW$ERAPAT$EXIT$EXPREG
$FAO$FILESCAN$FIND_HELD$FIND_HOLDER$FINISH_RDB
$FORCEX$FORMAT_ACL$FORMAT_AUDIT$GETDVI$GETDVIW
$GETJPI$GETJPIW$GETLKI$GETLKIW$GETMSG$GETQUI$GETQUIW
$GETSYI$GETSYIW$GETTIM$GETUAI$GRANTID$HASH_PASSWORD
$HIBER$IDTOASC$LCKPAG$LKWSET$MGBLSC$MOD_HOLDER
$MOD_IDENT$MOUNT$MTACCESS$NUMTIM$PARSE_ACL
$PREPARE_RU$PROCESS_SCAN$PURGWS$PUTMSG$QIO
$QIOW$READEF$RELEASE_VP$REM_HOLDER$REM_IDENT
$RESTORE_VP_EXCEPTION$RESTORE_VP_STATE$RESUME$REVOKID
$SAVE_VP_EXCEPTION$SCHDWK$SETAST$SETEF$SETEXV
$SETIME$SETIMR$SETPRA$SETPRI$SETPRN$SETPRT$SETPRV
$SETRWM$SETSFM$SETSSF$SETSTK$SETSWM$SETUAI$SNDERR
$SNDJBC$SNDJBCW$SNDOPR$START_RU$START_TRANS
$START_TRANSW$SUSPND$SYNCHSYS$RMSRUNDWNSYS$SETDDIR
SYS$SETDFPROT$TRNLNM$ULKPAG$ULWSET$UNWIND$UPDSEC
$UPDSECW$WAITFR$WAKE$WFLAND$WFLOR
$ABORT_RU
Applicable only if you have the RMS Journaling option. See the VAX
RMS Journaling Manual.
The Abort Recovery Unit Service terminates the current recovery unit
and restores all connected files to their states before the recovery
unit was started, for an application using RMS Journaling. You can
abort a recovery unit at any time after you invoke the $START_RU
service and before you invoke the $END_RU or $COMMIT_RU service.
Note that you can use the $ABORT_RU service after using the
$PREPARE_RU service, as long as you have not issued a call to the
$COMMIT_RU service.
After you abort the recovery unit, all files that were connected to
the recovery unit during $START_RU are available for further
processing. Remember that the $ABORT_RU call restores only the
records for those files that were marked for recovery unit journaling and
connected to the current recovery unit.
Format:
SYS$ABORT_RU ru_handle
Arguments:
ru_handle
VMS Usage: ru_handle
type: longword (unsigned)
access: read only
mechanism: by reference
The ru_handle argument is the address of an unsigned longword that
contains the recovery unit handle returned by the $START_RU system
service.
$ABORT_TRANS
Aborts a transaction; it can be called before the transaction is
committed.
Format:
SYS$ABORT_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, $ABORT_TRANS uses only the low-
order byte. If you do not specify the efn, $ABORT_TRANS sets the
event flag to 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.
$ABORT_TRANS Operation Flag
Flag Description
DDTM$M_SYNC Indicates successful synchronous completions 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.
If you specify astadr, the AST routine executes at the same access
mode as the caller of the $ABORT_TRANS service.
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) structure that
designates the transaction to be aborted. The default value for
this parameter is the current transaction.
$ABORT_TRANSW
Aborts a transaction; it can be called before the transaction is
committed.
$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; $ABORT_TRANS aborts a transaction 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.
For additional information about system service completion, refer
to the Synchronize ($SYNCH) service and to the Introduction to VMS
System Services.
Format:
SYS$ABORT_TRANSW [efn] ,[flags] ,iosb ,[astadr] ,[astprm]
,[tid]
$ADD_HOLDER
The Add Holder Record to Rights Database service adds the specified
holder record to the target identifier.
Format:
SYS$ADD_HOLDER id ,holder ,[attrib]
Arguments:
id
VMS usage: rights_id
type: longword (unsigned)
access: read only
mechanism: by value
Target identifier granted to the specified holder when $ADD_HOLDER
completes execution. The id argument is a longword containing the
binary value of the target identifier.
holder
VMS usage: rights_holder
type: quadword (unsigned)
access: read only
mechanism: by reference
Holder identifier that is granted access to the target identifier
when $ADD_HOLDER completes execution. The holder argument is the
address of a quadword data structure that consists of a longword
containing the holder's UIC identifier followed by a longword
containing a value of zero.
attrib
VMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by value
Attributes to be placed in the holder record when the $ADD_HOLDER
completes execution. The attrib argument is a longword containing a
bitmask specifying the attributes. A holder is granted a specified
attribute only if the target identifier has the attribute.
$ADD_IDENT
The Add Identifier to Rights Database service adds the specified
identifier to the rights database.
Format:
SYS$ADD_IDENT name ,[id] ,[attrib] ,[resid]
Arguments:
name
VMS usage: char-string
type: character-coded text string
access: read only
mechanism: by descriptor--fixed
length string descriptor
Identifier name to be added to the rights database when $ADD_IDENT
completes execution. The name argument is the address of the
descriptor pointing to the identifier name string.
id
VMS usage: rights_id
type: longword (unsigned)
access: read only
mechanism: by value
Identifier to be created when $ADD_IDENT completes execution. The
id argument is a longword containing the binary value of the
identifier to be created.
attrib
VMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by value
Attributes placed in the identifier's record when $ADD_IDENT
completes execution. The attrib argument is a longword containing a
bitmask specifying the attributes.
resid
VMS usage: rights_id
type: longword (unsigned)
access: write only
mechanism: by reference
Identifier value assigned by the system when $ADD_IDENT completes
execution. The resid argument is the address of a longword in which
the system-assigned identifier value is written.
$ADJSTK
The Adjust Outer Mode Stack Pointer service modifies the stack
pointer for a less privileged access mode. This service is used by
the operating system to modify a stack pointer for a less privileged
access mode after placing arguments on the stack.
Format:
SYS$ADJSTK [acmode] ,[adjust] ,newadr
Arguments:
acmode
VMS usage: access_mode
type: longword (unsigned)
access: read only
mechanism: by value
Access mode for which the stack pointer is to be adjusted. The
acmode argument is this longword value. If not specified, a default
value of 0 (kernel access mode) is used.
adjust
VMS usage: word_signed
type: word (signed)
access: read only
mechanism: by value
Signed adjustment value to be used to modify the value specified by
the newadr argument. The adjust argument is a signed longword,
which is the adjustment value.
newadr
VMS usage: address
type: longword (unsigned)
access: modify
mechanism: by reference
Value that $ADJUST is to adjust. The newadr argument is the address
of this longword value. The value specified by this argument is
both read and written by $ADJSTK. $ADJSTK reads the value specified
and adjusts it by the value of the adjust argument (if specified).
After this adjustment is made, $ADJSTK writes the adjusted value
back into the longword specified by newadr and then loads the stack
pointer with the adjusted value.
$ADJWSL
The Adjust Working Set Limit service adjusts a process's current
working set limit by the specified number of pages and returns the
new value to the caller. The working set limit specifies the
maximum number of process pages that may be resident in physical
memory.
Format:
SYS$ADJWSL [pagcnt] ,[wsetlm]
Arguments:
pagcnt
VMS usage: longword_signed
type: longword (signed)
access: read only
mechanism: by value
Signed adjustment value specifying the number of pages to add (if
positive) or subtract (if negative) from the current working set
limit. The pagcnt argument is this signed longword value.
wsetlm
VMS usage: longword_unsigned
type: longword (unsigned)
access: write only
mechanism: by reference
Value of the working set limit, returned by $ADJWSL. The wsetlm
argument is the address of this longword value. The wsetlm argument
specifies the newly adjusted value if pagcnt was specified, and it
specifies the old, unadjusted value if pagcnt was not specified.
$ALLOC
The Allocate Device service allocates a device for exclusive use by
a process and its subprocesses. No other process can allocate the
device or assign channels to it until the image that called $ALLOC
exits or explicitly deallocates the device with the Deallocate
Device ($DALLOC) service.
Format:
SYS$ALLOC devnam ,[phylen] ,[phybuf] ,[acmode] ,[flags]
Arguments:
devnam
VMS usage: device_name
type: character-coded text string
access: read only
mechanism: by descriptor--fixed
length string descriptor
Device name of the device to be allocated. The devnam argument is
the address of a character string descriptor pointing to the device
name string.
phylen
VMS usage: word_unsigned
type: word (unsigned)
access: write only
mechanism: by reference
Word into which $ALLOC writes the length of the device name string
for the device it has allocated. The phylen is the address of this
word.
phybuf
VMS usage: device_name
type: character-coded text string
access: write only
mechanism: by descriptor--fixed
length string descriptor
Buffer into which $ALLOC writes the device name string for the
device it has allocated. The phybuf is the address of a character
string descriptor pointing to this buffer.
acmode
VMS usage: access_mode
type: longword (unsigned)
access: read only
mechanism: by value
Access mode to be associated with the allocated device. The acmode
argument is a longword containing the access mode.
flags
VMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by value
Longword of status flags indicating whether to interpret the devnam
argument as type of the device to be allocated. Only one flag
exists, bit 0. When it is set, the $ALLOC service allocates the
first available device having the type specified in the devnam
argument.
$ASCEFC
The Associate Common Event Flag Cluster service causes a named
common event flag cluster to be associated with a process for the
execution of the current image and to be assigned a process-local
cluster number for use with other event flag services. If the named
cluster does not exist but the process has suitable privilege, the
service creates the cluster.
Format:
SYS$ASCEFC efn ,name ,[prot] ,[perm]
Arguments:
efn
VMS usage: ef_number
type: longword (unsigned)
access: read only
mechanism: by value
Number of any event flag contained within the desired common event
flag cluster. The efn argument is a longword value specifying this
number.
name
VMS usage: ef_cluster_name
type: character-coded text string
access: read only
mechanism: by descriptor--fixed
length string descriptor
Name of the common event flag cluster with which to associate. The
name argument is the address of a character string descriptor
pointing to this name string.
prot
VMS usage: boolean
type: byte (unsigned)
access: read only
mechanism: by value
Protection specifier that allows or disallows access to the common
event flag cluster by processes with the same UIC group number as
the creating process. The prot argument is a longword value, which
is interpreted as Boolean.
perm
VMS usage: boolean
type: byte (unsigned)
access: read only
mechanism: by value
Permanent specifier that marks a common event flag cluster as either
permanent or temporary. The perm argument is a longword value,
which is interpreted as Boolean.
$ASCTIM
The Convert Binary Time to ASCII String service converts an absolute
or delta time from 64-bit system time format to an ASCII string.
Format:
SYS$ASCTIM [timlen] ,timbuf ,[timadr] ,[cvtflg]
Arguments:
timlen
VMS usage: word_unsigned
type: word (unsigned)
access: write only
mechanism: by reference
Length (in bytes) of the ASCII string returned by $ASCTIM. The
timlen argument is the address of a word containing this length.
timbuf
VMS usage: time_name
type: character-coded text string
access: write only
mechanism: by descriptor--fixed
length string descriptor
Buffer into which $ASCTIM writes the ASCII string. The timbuf
argument is the address of a character string descriptor pointing to
the buffer.
timadr
VMS usage: date_time
type: quadword (unsigned)
access: read only
mechanism: by reference
Time value that $ASCTIM is to convert. The timadr argument is the
address of this 64-bit time value. A positive time value represents
an absolute time. A negative time value represents a delta time.
If a delta time is specified, it must be less than 10,000 days.
cvtflg
VMS usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by value
Conversion indicator specifying which date and time fields $ASCTIM
should return. The cvtflg argument is a longword value, which is
interpreted as Boolean. A value of 1 specifies that $ASCTIM should
return only the hour, minute, second, and hundredth of second
fields. A value of 0 (the default) specifies that $ASCTIM should
return the full date and time.
$ASCTOID
The Translate Identifier Name to Identifier service translates the
specified identifier name into its binary identifier value.
Format:
SYS$ASCTOID name ,[id] ,[attrib]
Arguments:
name
VMS usage: char_string
type: character-coded text string
access: read only
mechanism: by descriptor--fixed
length string descriptor
Identifier name translated when $ASCTOID completes execution. The
name argument is the address of a descriptor pointing to the
identifier name.
id
VMS usage: rights_id
type: longword (unsigned)
access: write only
mechanism: by reference
Identifier value resulting when $ASCTOID completes execution. The
id argument is the address of a longword in which the identifier
value is written.
attrib
VMS usage: mask_longword
type: longword (unsigned)
access: write only
mechanism: by reference
Attributes associated with the identifier returned in id when
$ASCTOID completes execution. The attrib argument is the address of
a longword containing a bitmask specifying the attributes.
$ASSIGN
The Assign I/O Channel service (1) provides a process with an I/O
channel so that input/output operations can be performed on a device
or (2) establishes a logical link with a remote node on a network.
Format:
SYS$ASSIGN devnam ,chan ,[acmode] ,[mbxnam]
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 most privileged access mode used is
the access mode of the caller. I/O operations on the channel can
only be performed from equal and more privileged 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.
$BINTIM
The Convert ASCII String to Binary Time service converts an ASCII
string to an absolute or delta time value in the system 64-bit time
format suitable for input to the Set Timer ($SETIMR) or Schedule
Wakeup ($SCHDWK) services.
Format:
SYS$BINTIM timbuf ,timadr
Arguments:
timbuf
VMS usage: time_name
type: character-coded text string
access: read only
mechanism: by descriptor--fixed
length string descriptor
The timbuf argument specifies the address of a character string
descriptor pointing to the VMS time string. The VMS time
string specifies the absolute or delta time to be converted by
$BINTIM. The VMS Data Type Table describes the VMS time
string.
timadr
VMS usage: date_time
type: quadword (unsigned)
access: write only
mechanism: by reference
The timadr argument is the address of the VMS quadword system
time, which receives the converted time.
$BRKTHRU
The Breakthrough service sends a message to one or more terminals.
The $BRKTHRU service completes asynchronously; that is, it returns
to the caller after queueing the message request, without waiting
for the message to be written to the specified terminal(s).
For synchronous completion, use the Breakthrough and Wait
($BRKTHRUW) service. The $BRKTHRUW service is identical to the
$BRKTHRU service in every way except that $BRKTHRUW returns to the
caller after the message is written to the specified terminal(s).
The $BRKTHRU service supersedes the Broadcast ($BRDCST) service.
New programs should be written using $BRKTHRU, and old programs
using $BRDCST should be converted to use $BRKTHRU as convenient.
Format:
SYS$BRKTHRU [efn] ,msgbuf [,sendto] [,sndtyp] [,iosb]
[,carcon] [,flags] [,reqid] [,timout] [,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 the message has been written
to the specified terminal(s). The efn argument is a longword
containing this number.
msgbuf
VMS usage: char_string
type: character-coded text string
access: read only
mechanism: by descriptor--fixed
length string descriptor
Message text to be sent to the specified terminal(s). The msgbuf
argument is the address of a descriptor pointing to this message
text.
sendto
VMS usage: char_string
type: character-coded text string
access: read only
mechanism: by descriptor--fixed
length string descriptor
Name of a single device (terminal) or single username to which to
send the message. The sendto argument is the address of a
descriptor pointing to this name.
sndtyp
VMS usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by value
Terminal type to which $BRKTHRU is to send the message. The sndtyp
argument is a longword value specifying the terminal type.
iosb
VMS usage: io_status_block
type: quadword (unsigned)
access: write only
mechanism: by reference
I/O status block that is to receive the final completion status.
The iosb is the address of this quadword block.
carcon
VMS usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by value
Carriage control specifier indicating the carriage control sequence
that is to follow the message that $BRKTHRU sends to the
terminal(s). The carcon argument is a longword containing the
carriage control specifier.
flags
VMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by value
Flag bit mask specifying options for the $BRKTHRU operation. The
flags argument is a longword value that is the logical OR of each
desired flag option.
reqid
VMS usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by value
Class requestor identification, which identifies to $BRKTHRU the
application (or image) that is calling $BRKTHRU. The reqid argument
is this longword identification value.
timout
VMS usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by value
Timeout value, which is the number of seconds that must elapse
before an attempted write by $BRKTHRU to a terminal is considered to
have failed. The timout argument is this longword value (in
seconds).
astadr
VMS usage: ast_procedure
type: procedure entry mask
access: call without stack unwinding
mechanism: by
reference
AST service routine to be executed after $BRKTHRU has sent the
message to the specified terminal(s). 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 routine specified by the
astadr argument. The astprm argument specifies this longword
parameter.
$BRKTHRUW
The Breakthrough and Wait service sends a message to one or more
terminals.
The $BRKTHRUW service operates synchronously; that is, it returns to
the caller after the message has been sent to the specified
terminal(s).
For asynchronous operations, use the Breakthrough ($BRKTHRU)
service; $BRKTHRU returns to the caller after queueing the message
request, without waiting for the message to be delivered.
In all other respects, $BRKTHRUW is identical to $BRKTHRU. Refer to
the documentation of $BRKTHRU for all other information about the
$BRKTHRUW service.
The $BRKTHRU and $BRKTHRUW services supersede the Broadcast
($BRDCST) service. New code should be written using $BRKTHRU or
$BRKTHRUW, and old code using $BRDCST should be converted to use
$BRKTHRU or $BRKTHRUW as convenient. $BRDCST is now an obsolete
system service and will no longer be enhanced.
Format:
SYS$BRKTHRUW [efn] ,msgbuf [,sendto] [,sndtyp] [,iosb]
[,carcon] [,flags] [,reqid] [,timout] [,astadr]
[,astprm]
$CANCEL
The Cancel I/O On Channel service cancels all pending I/O requests
on a specified channel. In general, this includes all I/O requests
that are queued as well as the request currently in progress.
Format:
SYS$CANCEL chan
ARGUMENT
chan
VMS usage: channel
type: word (unsigned)
access: read only
mechanism: by value
I/O channel on which I/O is to be canceled. The chan argument is a
longword containing the channel number.
$CANEXH
The Cancel Exit Handler service deletes an exit control block from
the list of control blocks for the calling access mode. Exit
control blocks are declared by the Declare Exit Handler ($DCLEXH)
service and are queued according to access mode in a last-in
first-out order.
Format:
SYS$CANEXH [desblk]
ARGUMENT
desblk
VMS usage: exit_handler_block
type: longword (unsigned)
access: read only
mechanism: by reference
Control block describing the exit handler to be canceled. The
desblk is the address of this control block. If desblk is not
specified or is specified as 0, all exit control blocks are canceled
for the current access mode.
$CANTIM
The Cancel Timer Request service cancels all or a selected subset of
the Set Timer requests previously issued by the current image
executing in a process. Cancellation is based on the request
identification specified in the Set Timer ($SETIMR) service. If
more than one timer request was given the same request
identification, all requests with that request identification are
canceled.
Format:
SYS$CANTIM [reqidt] ,[acmode]
Arguments:
reqidt
VMS usage: user_arg
type: longword (unsigned)
access: read only
mechanism: by value
Request identification of the timer request(s) to be canceled. The
reqidt argument is a longword containing this identification. If
reqidt is specified as 0 (the default), all timer requests are
canceled.
acmode
VMS usage: access_mode
type: longword (unsigned)
access: read only
mechanism: by value
Access mode of the request(s) to be canceled. The acmode argument
is a longword containing the access mode.
$CANWAK
The Cancel Wakeup service removes all scheduled wake-up requests for
a process from the timer queue, including those made by the caller
or by other processes. Scheduled wake-up requests are made with the
Schedule Wakeup ($SCHDWK) service.
Format:
SYS$CANWAK [pidadr] ,[prcnam]
Arguments:
pidadr
VMS usage: process_id
type: longword (unsigned)
access: modify
mechanism: by reference
Process identification (PID) of the process for which wakeups are to
be canceled. The pidadr is the address of a longword specifying the
PID.
prcnam
VMS usage: process_name
type: character-coded text string
access: read only
mechanism: by descriptor--fixed
length string descriptor
Name of the process for which wakeups are to be canceled. The
prcnam argument is the address of a character string descriptor
pointing to the process name string.
$CHANGE_ACL
The Change Access Control List service creates or modifies an
object's access control list.
Format:
SYS$CHANGE_ACL [chan] ,objtyp ,[objnam] ,itmlst ,[acmode]
,[nullarg] ,[contxt] ,[nullarg] ,[nullarg]
Arguments:
chan
VMS usage: channel
type: word (unsigned)
access: read only
mechanism: by value
Number of the I/O channel assigned to the object whose ACL is
modified when $CHANGE_ACL completes execution. The chan argument is
a word containing the number of the channel. If objnam is
specified, chan must be omitted or specified as zero.
objtyp
VMS usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
Type of object whose ACL is modified when $CHANGE_ACL completes
execution. The objtyp argument is the address of a longword
containing a value indicating whether the object is a file or a
device. The symbols are defined in the system macro library
($ACLDEF).
objnam
VMS usage: char_string
type: character-coded text string
access: read only
mechanism: by descriptor--fixed
length string descriptor
Name of the object whose ACL is modified when $CHANGE_ACL completes
execution. The objnam argument is the address of a descriptor
pointing to a character text string containing the name of the
object. The maximum length of objnam depends on the object.
itmlst
VMS usage: item_list_3
type: longword (unsigned)
access: read only
mechanism: by reference
Modifications to be made to the ACL when $CHANGE_ACL completes
execution. The itmlst argument is the address of a variable length
data structure defining the changes to be made.
acmode
VMS usage: access_mode
type: longword (unsigned)
access: read only
mechanism: by reference
Access mode to use in checking file access protection. The acmode
argument is the address of a longword containing the access mode.
Acmode defaults to kernel mode; however, the system compares acmode
against the caller's access mode and uses the least privileged mode.
nullarg
VMS usage: null_arg
type: longword (unsigned)
access: read only
mechanism: by value
Place-holding argument. This argument is reserved to DIGITAL.
contxt
VMS usage: context
type: longword (unsigned)
access: modify
mechanism: by reference
Context value that points to an ACE. The contxt argument is the
address of a longword containing the context value.
$CHECK_ACCESS
The Check Access system service determines, on behalf of a
third-party user, whether the user can access the object specified.
Format:
SYS$CHECK_ACCESS objtyp ,objnam ,usrnam ,itmlst
Arguments:
objtyp
VMS usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
Type of object being accessed. The objtyp argument is the address
of a longword containing a value specifying the type of object. The
symbols are defined in the system macro library ($ACLDEF).
objnam
VMS usage: char_string
type: character-coded text string
access: read only
mechanism: by descriptor--fixed
length string descriptor
Name of the object being accessed. The objnam argument is the
address of a descriptor pointing to a character text string
containing the name of the object. The maximum length of objnam
depends on the object.
usrnam
VMS usage: char_string
type: character-coded text string
access: read only
mechanism: by descriptor--fixed
length string descriptor
Name of the user attempting access. The usrnam argument is the
address of a descriptor pointing to a character text string
containing the user name of the user attempting to gain access to
the specified object. The user name string may contain a maximum of
12 alphanumeric characters.
itmlst
VMS usage: item_list_3
type: longword (unsigned)
access: read only
mechanism: by reference
Attributes describing how the object is to be accessed and
information returned after $CHECK_ACCESS performs the protection
check (for instance, security alarm information).
$CHKPRO
The Check Access Protection system service determines whether an
accessor with the specified rights and privileges can access an
object with the specified attributes.
Format:
SYS$CHKPRO itmlst
Arguments:
itmlst
VMS usage: item_list_3
type: longword (unsigned)
access: read only
mechanism: by reference
Protection attributes of the object and the rights and privileges of
the accessor used when $CHKPRO determines if the accessor can access
the object. The itmlst argument is the address of an item list of
descriptors used to specify the protection attributes of the object
and the rights and privileges of the accessor.
$CLREF
The Clear Event Flag service clears (sets to 0) an event flag in a
local or common event flag cluster.
Format:
SYS$CLREF efn
Argument
efn
VMS usage: ef_number
type: longword (unsigned)
access: read only
mechanism: by value
Number of the event flag to be cleared. The efn argument is a
longword containing this number.
$CMEXEC
The Change to Executive Mode service changes the access mode of the
calling process to executive mode. This service allows a process to
change its access mode to executive, execute a specified routine,
and then return to the access mode in effect before the call was
issued.
Format:
SYS$CMEXEC routin ,[arglst]
Arguments:
routin
VMS usage: procedure
type: procedure entry mask
access: call without stack unwinding
mechanism: by reference
Routine to be executed while the process is in executive mode. The
routin argument is the address of the entry point to this routine.
arglst
VMS usage: arg_list
type: longword (unsigned)
access: read only
mechanism: by reference
Argument list to be passed to the routine specified by the routin
argument. The arglst argument is the address of this argument list.
$CMKRNL
The Change to Kernel Mode service changes the access mode of the
calling process to kernel mode. This service allows a process to
change its access mode to kernel, execute a specified routine, and
then return to the access mode in effect before the call was issued.
Format:
SYS$CMKRNL routin ,[arglst]
Arguments:
routin
VMS usage: procedure
type: procedure entry mask
access: call without stack unwinding
mechanism: by reference
Routine to be executed while the process is in kernel mode. The
routin argument is the address of the entry point to this routine.
arglst
VMS usage: arg_list
type: longword (unsigned)
access: read only
mechanism: by reference
Argument list to be passed to the routine specified by the routin
argument. The arglst argument is the address of this argument list.
$CNTREG
The Contract Program/Control Region service deletes a specified
number of pages from the current end of the program or control
region of a process's virtual address space. The deleted pages
become inaccessible, and references to them cause access violations.
Format:
SYS$CNTREG pagcnt ,[retadr] ,[acmode] ,[region]
Arguments:
pagcnt
VMS usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by value
Number of pages to be deleted from the current end of the program or
control region. The pagcnt argument is a longword specifying this
number.
retadr
VMS usage: address_range
type: longword (unsigned)
access: write only
mechanism: by reference
Starting and ending pages of the deleted area. The retadr argument
is the address of a two-longword array to receive the virtual
addresses of the starting page and ending page of the deleted area.
acmode
VMS usage: access_mode
type: longword (unsigned)
access: read only
mechanism: by value
Access mode of the owner of the pages to be deleted. The acmode
argument is a longword containing the access mode.
region
VMS usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by value
Indicator specifying which region of memory (P0 or P1) is to be
contracted. The region argument is a longword containing the
indicator. A value of 0 (the default) indicates that the program
region (P0 region) is to be contracted, and a value of 1 indicates
that the control region (P1 region) is to be contracted.
$COMMIT_RU
Applicable only if you have the RMS Journaling option. See the VAX
RMS Journaling Manual.
The Commit Recovery Unit Service is used only after a call to the
Prepare Recovery Unit Service in an application using RMS Journaling
or after a call to the $END_RU service that has returned a status of
RUF$_RUNOTCOM. When you use $COMMIT_RU, the recovery unit is
terminated, and the records that were modified within the recovery
unit are available for further processing. If no processing takes
place in your application between the $PREPARE_RU and $COMMIT_RU
calls, you can replace these two calls with the single $END_RU call.
Format:
SYS$COMMIT_RU ru_handle
Arguments:
ru_handle
VMS Usage: ru_handle
type: longword (unsigned)
access: read only
mechanism: by reference
The ru_handle argument is the address of an unsigned longword that
contains the recovery unit handle returned by the $START_RU system
service.
$CRELNM
The Create Logical Name service creates a logical name and specifies
its equivalence name(s).
Format:
SYS$CRELNM [attr] ,tabnam ,lognam ,[acmode] ,[itmlst]
Arguments:
attr
VMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Attributes to be associated with the logical name. The attr
argument is the address of a longword bit mask specifying these
attributes.
tabnam
VMS usage: logical_name
type: character-coded text string
access: read only
mechanism: by descriptor--fixed
length string descriptor
Name of the table in which to create the logical name. The tabnam
argument is the address of a descriptor that points to the name of
this table. This argument is required.
lognam
VMS usage: logical_name
type: character-coded text string
access: read only
mechanism: by descriptor--fixed
length string descriptor
Name of the logical name to be created. The lognam argument is the
address of a descriptor that points to the logical name string.
Logical name strings of logical names created within either the
system or process directory table must consist of alphanumeric
characters, dollar signs, and underscores; the maximum length is 31
characters. The maximum length of logical name strings created
within other tables is 255 characters with no restrictions on the
types of characters that can be used. This argument is required.
acmode
VMS usage: access_mode
type: byte (unsigned)
access: read only
mechanism: by reference
Access mode to be associated with the logical name. The acmode
argument is the address of a byte that specifies the access mode.
itmlst
VMS usage: item_list_3
type: longword (unsigned)
access: read only
mechanism: by reference
Item list describing the equivalence name(s) to be defined for the
logical name and information to be returned to the caller. The
itmlst argument is the address of a list of item descriptors, each
of which specifies information about an equivalence name. The list
of item descriptors is terminated by a longword of 0. This argument
is required.
$CRELNT
The Create Logical Name Table service creates a process-private or
shareable logical name table.
Format:
SYS$CRELNT [attr] ,[resnam] ,[reslen] ,[quota]
,[promsk] ,[tabnam] ,partab ,[acmode]
Arguments:
attr
VMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Attributes to affect the creation of the logical name table and to
be associated with the newly created logical name table. The attr
argument is the address of a longword bit mask specifying these
attributes.
resnam
VMS usage: logical_name
type: character-coded text string
access: write only
mechanism: by descriptor--fixed
length string descriptor
Name of the newly created logical name table, returned by $CRELNT.
The resnam argument is the address of a descriptor pointing to this
name. The name is a character string whose maximum length is 31
characters.
reslen
VMS usage: word_unsigned
type: word (unsigned)
access: write only
mechanism: by reference
Length in bytes of the name of the newly created logical name table,
returned by $CRELNT. The reslen argument is the address of a word
to receive this length.
quota
VMS usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
Maximum number of bytes of memory to be allocated for logical names
contained in this logical name table. The quota argument is the
address of a longword specifying this value.
promsk
VMS usage: file_protection
type: word (unsigned)
access: read only
mechanism: by reference
Protection mask to be associated with the newly created shareable
logical name table. The promsk argument is the address of a word
that contains a value that represents four 4-bit fields, where each
field describes the type of access allowed for system, owner, group,
and world users.
tabnam
VMS usage: logical_name
type: character-coded text string
access: read only
mechanism: by
descriptor--fixed length string descriptor
The name of the new logical name table. The tabnam argument is the
address of a character string descriptor pointing to this name
string. Table names are contained in either the process or system
directory table (LNM$PROCESS_DIRECTORY or LNM$SYSTEM_DIRECTORY).
Therefore table names must consist of alphanumeric characters,
dollar signs, and underscores; the maximum length is 31 characters.
partab
VMS usage: char_string
type: character-coded text string
access: read only
mechanism: by descriptor--fixed
length string descriptor
Parent table name. The partab argument is the address of a
character string descriptor pointing to this name string. The only
valid values for this argument are the names of the directory tables
LNM$PROCESS_DIRECTORY or LNM$SYSTEM_DIRECTORY. SYSPRV privilege is
required to specify the system directory table LNM$SYSTEM_DIRECTORY.
This argument is required.
acmode
VMS usage: access_mode
type: byte (unsigned)
access: read only
mechanism: by reference
Access mode to be associated with the newly created logical name
table. The acmode argument is the address of a byte containing this
access mode. The $PSLDEF macro defines symbolic names for the four
access modes.
$CREMBX
The Create Mailbox and Assign Channel service 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 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]
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. A value of 1
specifies a permanent mailbox; a value of 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
Channel 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 maxmsg is not specified or is specified as 0, VMS
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 longword
value containing this number. If bufquo is not specified or is
specified 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.
$CREPRC
The Create Process service creates a subprocess or detached process
on behalf of the calling process.
Format:
SYS$CREPRC [pidadr] ,[image] ,[input] ,[output] ,[error]
,[prvadr] ,[quota] ,[prcnam] ,[baspri] ,[uic]
,[mbxunt] ,[stsflg]
Arguments:
pidadr
VMS usage: process_id
type: longword (unsigned)
access: write only
mechanism: by reference
Process identification (PID) of the newly created process. The
pidadr argument is the address of a longword into which $CREPRC
writes the PID.
image
VMS usage: logical_name
type: character-coded text string
access: read only
mechanism: by descriptor--fixed
length string descriptor
Name of the image to be activated in the newly created process. The
image argument is the address of a character string descriptor
pointing to the file specification of the image.
input
VMS usage: logical_name
type: character-coded text string
access: read only
mechanism: by descriptor--fixed
length string descriptor
Equivalence name to be associated with the logical name SYS$INPUT in
the logical name table of the created process. The input argument
is the address of a character string descriptor pointing to the
equivalence name string.
output
VMS usage: logical_name
type: character-coded text string
access: read only
mechanism: by descriptor--fixed
length string descriptor
Equivalence name to be associated with the logical name SYS$OUTPUT
in the logical name table of the created process. The output
argument is the address of a character string descriptor pointing to
the equivalence name string.
error
VMS usage: logical_name
type: character-coded text string
access: read only
mechanism: by descriptor--fixed
length string descriptor
Equivalence name to be associated with the logical name SYS$ERROR in
the logical name table of the created process. The error argument
is the address of a character string descriptor pointing to the
equivalence name string.
prvadr
VMS usage: mask_privileges
type: quadword (unsigned)
access: read only
mechanism: by reference
Privileges to be given to the created process. The prvadr argument
is the address of a quadword bit vector wherein each bit corresponds
to a privilege; setting a bit gives the privilege.
quota
VMS usage: item_quota_list
type: longword (unsigned)
access: read only
mechanism: by reference
Process quotas to be established for the created process; these
quotas limit the created process's use of system resources. The
quota argument is the address of a list of quota descriptors, where
each quota descriptor consists of a 1-byte quota name followed by a
longword that specifies the desired value for that quota. The list
of quota descriptors is terminated by the symbolic name
PQL$_LISTEND.
prcnam
VMS usage: process_name
type: character-coded text string
access: read only
mechanism: by descriptor--fixed
length string descriptor
Process name to be assigned to the created process. The prcnam is
the address of a character string descriptor pointing to a 1- to
15-character process name string.
baspri
VMS usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by value
Base priority to be assigned to the created process. The baspri
argument is a longword value in the range 0 to 31, where 31 is the
highest possible priority and 0 is the lowest. Normal priorities
are in the range 0 through 15, and real-time priorities are in the
range 16 through 31.
uic
VMS usage: uic
type: longword (unsigned)
access: read only
mechanism: by value
User identification code (UIC) to be assigned to the created
process. The uic argument is a longword value containing the UIC.
mbxunt
VMS usage: word_unsigned
type: word (unsigned)
access: read only
mechanism: by value
Unit number of a mailbox to receive a termination message when the
created process is deleted. The mbxunt argument is a word
containing this number.
stsflg
VMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by value
Options selected for the created process. The stsflg argument is a
longword bit vector wherein a bit corresponds to an option. Only
bits 0 to 10 are used; bits 11 to 31 are reserved and must be 0.
$CREATE_RDB
The Create Rights Database service initializes a rights database.
Format:
SYS$CREATE_RDB [sysid]
Arguments:
sysid
VMS usage: system_access_id
type: quadword (unsigned)
access: read only
mechanism: by reference
System identification value associated with the rights database when
$CREATE_RDB completes execution. The sysid argument is the address
of quadword containing the system identification value. If sysid is
omitted, the current system time in 64-bit format is used.
$CRETVA
The Create Virtual Address Space service adds a range of demand-zero
allocation pages to a process's virtual address space for the
execution of the current image.
Format:
SYS$CRETVA inadr ,[retadr] ,[acmode]
Arguments:
inadr
VMS usage: address_range
type: longword (unsigned)
access: read only
mechanism: by reference
Address of a two-longword array containing the starting and ending
virtual addresses of the pages to be created. If the starting and
ending virtual addresses are the same, a single page is created.
Only the virtual page number portion of the virtual addresses is
used; the low-order 9 bits are ignored.
retadr
VMS usage: address_range
type: longword (unsigned)
access: write only
mechanism: by reference--array reference
or descriptor
Address of a two-longword array to receive the starting and ending
virtual addresses of the pages actually created.
acmode
VMS usage: access_mode
type: longword (unsigned)
access: read only
mechanism: by value
Access mode and protection for the new pages. The acmode argument
is a longword containing the access mode.
$CRMPSC
The Create and Map Section service allows a process to associate
(map) a section of its address space with (1) a specified section of
a file (a disk file section) or (2) with specified physical
addresses represented by page frame numbers (a page frame section).
This service also allows the process to create either type of
section, and to specify that that section be available only to the
creating process (private section) or to all processes that map to
it (global section).
Format:
SYS$CRMPSC [inadr] ,[retadr] ,[acmode] ,[flags] ,[gsdnam]
,[ident] ,[relpag] ,[chan] ,[pagcnt] ,[vbn] ,[prot]
,[pfc]
Arguments:
inadr
VMS usage: address_range
type: longword (unsigned)
access: read only
mechanism: by reference
Starting and ending virtual addresses into which the section is to
be mapped. The inadr is the address of a two-longword array
containing, in order, the starting and the ending process virtual
addresses. Only the virtual page number portion of each virtual
address is used; the low-order 9 bits are ignored.
retadr
VMS usage: address_range
type: longword (unsigned)
access: write only
mechanism: by
reference--array reference or descriptor
Starting and ending process virtual addresses into which the section
was actually mapped by $CRMPSC. The retadr is the address of a
two-longword array containing, in order, the starting and ending
process virtual addresses.
acmode
VMS usage: access_mode
type: longword (unsigned)
access: read only
mechanism: by value
Access mode that is to be the owner of the pages created during the
mapping. The acmode argument is a longword containing the access
mode.
flags
VMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by value
Flag mask specifying the type of section to be created or mapped to,
as well as its characteristics. The flags argument is a longword
bit vector wherein each bit corresponds to a flag. The $SECDEF
macro defines a symbolic name for each flag. The flags argument is
constructed by performing a logical OR operation on the symbol names
for all desired flags.
gsdnam
VMS usage: section_name
type: character-coded text string
access: read only
mechanism: by
descriptor--fixed length string descriptor
Name of the global section. The gsdnam is the address of a
character string descriptor pointing to this name string.
ident
VMS usage: section_id
type: quadword (unsigned)
access: read only
mechanism: by reference
Identification value specifying the version number of a global
section, and, for processes mapping to an existing global section,
the criteria for matching the identification. The ident argument is
the address of a quadword structure containing three fields.
relpag
VMS usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by value
Relative page number within the global section of the first page in
the section to be mapped. The relpag argument is a longword
containing this page number.
chan
VMS usage: channel
type: word (unsigned)
access: read only
mechanism: by value
Number of the channel on which the file has been accessed. The chan
argument is a word containing this number.
pagcnt
VMS usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by value
Number of pages in the section. The pagcnt argument is a longword
containing this number.
vbn
VMS usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by value
Virtual block number in the file that marks the beginning of the
section. The vbn argument is a longword containing this number. If
vbn is not specified or is specified as 0 (the default), the section
is created beginning with the first virtual block in the file.
prot
VMS usage: file_protection
type: longword (unsigned)
access: read only
mechanism: by value
Numeric value representing the protection mask to be applied to the
global section. This value is ORed with the protection mask
associated with the file; if the file protection does not allow
access to a particular category of user and the protection mask
allows access, access is denied.
pfc
VMS usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by value
Page fault cluster size. If specified, the cluster size indicates
how many pages are to be brought into memory when a page fault
occurs for a single page. This argument is not used for physical
page frame sections or for global sections in memory shared by
multiple processors.
$DACEFC
The Disassociate Common Event Flag Cluster service releases the
calling process's association with a common event flag cluster.
Format:
SYS$DACEFC efn
Argument
efn
VMS usage: ef_number
type: longword (unsigned)
access: read only
mechanism: by value
Number of any event flag in the common cluster to be disassociated.
The efn argument is a longword containing this number. The number
must be in the range of 64 through 95 for cluster 2, and 96 through
127 for cluster 3.
$DALLOC
The Deallocate Device service deallocates a previously allocated
device. The issuing process relinquishes exclusive use of the
device thus allowing other processes to assign or allocate that
device.
Format:
SYS$DALLOC [devnam] ,[acmode]
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 be deallocated. The devnam argument is the
address of a character string descriptor pointing to the device name
string. The string may be either a physical device name or a
logical name. If it is a logical name, it must translate to a
physical device name.
acmode
VMS usage: access_mode
type: longword (unsigned)
access: read only
mechanism: by value
Access mode on behalf of which the deallocation is to be performed.
The acmode argument is a longword containing the access mode.
$DASSGN
The Deassign I/O Channel service deassigns (releases) an I/O channel
that was acquired using the Assign I/O Channel ($ASSIGN) service.
Format:
SYS$DASSGN chan
Argument
chan
VMS usage: channel
type: word (unsigned)
access: read only
mechanism: by value
Number of the I/O channel to be deassigned. The chan argument is a
word containing this number.
$DCLAST
The Declare AST service queues an AST for the calling access mode or
for a less privileged access mode. For example, a routine executing
in supervisor mode can declare an AST for either supervisor or user
mode.
Format:
SYS$DCLAST astadr ,[astprm] ,[acmode]
Arguments:
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 to be passed to the AST routine specified by the
astadr argument. The astprm argument is a longword containing this
parameter.
acmode
VMS usage: access_mode
type: longword (unsigned)
access: read only
mechanism: by value
Access mode for which the AST is to be declared. The most
privileged access mode used is the access mode of the caller. The
resultant mode is the access mode for which the AST is declared.
$DCLCMH
The Declare Change Mode or Compatibility Mode Handler service
specifies the address of a routine to receive control when (1) a
Change Mode to User or Change Mode to Supervisor instruction trap
occurs, or (2) a compatibility mode fault occurs.
Format:
SYS$DCLCMH addres ,[prvhnd] ,[type]
Arguments:
addres
VMS usage: procedure
type: procedure entry mask
access: call without stack unwinding
mechanism: by
reference
Routine to receive control when a change mode trap or a
compatibility mode fault occurs. The addres argument is the address
of the entry mask to this routine.
prvhnd
VMS usage: address
type: longword (unsigned)
access: write only
mechanism: by reference
Address of a previously declared handler. The prvhnd argument is
the address of a longword containing the address of the previously
declared handler.
type
VMS usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by value
Handler type indicator. The type argument is a longword value. The
value 0 (the default) indicates that a change mode handler is to be
declared for the access mode at which the request is issued; the
value 1 specifies that a compatibility mode handler is to be
declared.
$DCLEXH
The Declare Exit Handler service declares an exit handling routine
that will receive control when an image exits. Image exit normally
occurs when the image currently executing in a process returns
control to the operating system. Image exit may also occur when the
Exit ($EXIT) or Force Exit ($FORCEX) services are called.
Format:
SYS$DCLEXH desblk
Argument
desblk
VMS usage: exit_handler_block
type: longword (unsigned)
access: read only
mechanism: by reference
Exit handler control block. The desblk is the address of this
control block.
$DELLNM
The Delete Logical Name service deletes all logical names with the
specified name at the specified access mode or outer access mode, or
it deletes all the logical names with the specified access mode or
outer access mode in a specified table. If any logical names being
deleted are also the names of logical name tables, then all of the
logical names contained within those tables and all of their
subtables are also deleted.
Format:
SYS$DELLNM tabnam ,[lognam] ,[acmode]
Arguments:
tabnam
VMS usage: logical_name
type: character-coded text string
access: read only
mechanism: by
descriptor--fixed length string descriptor
Name of a logical name table or name of a list of tables in which to
search for the logical name that is to be deleted. The tabnam
argument is the address of a descriptor that points to the table
name. This argument is required.
lognam
VMS usage: logical_name
type: character-coded text string
access: read only
mechanism: by
descriptor--fixed length string descriptor
Logical name to be deleted. The lognam argument is the address of a
descriptor that points to the logical name string.
acmode
VMS usage: access_mode
type: byte (unsigned)
access: read only
mechanism: by reference
Access mode to be used in the delete operation. The acmode argument
is the address of a byte containing this access mode. The $PSLDEF
macro defines symbolic names for the four access modes.
$DELMBX
The Delete Mailbox service marks a permanent mailbox for deletion.
The actual deletion of the mailbox and of its associated logical
name assignment occur when no more I/O channels are assigned to the
mailbox.
Format:
SYS$DELMBX chan
Argument
chan
VMS usage: channel
type: word (unsigned)
access: read only
mechanism: by value
Number of the channel assigned to the mailbox that is to be deleted.
The chan is a word containing this number.
$DELPRC
The Delete Process service allows a process to delete itself or
another process.
Format:
SYS$DELPRC [pidadr] ,[prcnam]
Arguments:
pidadr
VMS usage: process_id
type: longword (unsigned)
access: modify
mechanism: by reference
Process identification (PID) of the process to be deleted. The
pidadr argument is the address of a longword that contains the PID.
prcnam
VMS usage: process_name
type: character-coded text string
access: read only
mechanism: by
descriptor--fixed length string descriptor
Process name of the process to be deleted. The prcnam is the
address of a character string descriptor pointing to a 1- to
15-character process name string.
$DELTVA
The Delete Virtual Address Space service deletes a range of
addresses from a process's virtual address space. Upon successful
completion of the service, the deleted pages are inaccessible, and
references to them cause access violations.
Format:
SYS$DELTVA inadr ,[retadr] ,[acmode]
Arguments:
inadr
VMS usage: address_range
type: longword (unsigned)
access: read only
mechanism: by reference
Starting and ending virtual addresses of the pages to be deleted.
The inadr argument is the address of a two-longword array
containing, in order, the starting and the ending process virtual
addresses. If the starting and ending virtual addresses are the
same, a single page is deleted. Only the virtual page number
portion of each virtual address is used; the low-order 9 bits are
ignored.
retadr
VMS usage: address_range
type: longword (unsigned)
access: write only
mechanism: by reference
Starting and ending process virtual addresses of the pages that
$DELTVA has actually deleted. The retadr is the address of a
two-longword array containing, in order, the starting and ending
process virtual addresses.
acmode
VMS usage: access_mode
type: longword (unsigned)
access: read only
mechanism: by value
Access mode on behalf of which the service is to be performed. The
acmode argument is a longword containing the access mode.
$DEQ
The Dequeue Lock Request service dequeues (unlocks) granted locks;
dequeues the sublocks of a lock; or cancels an ungranted lock
request. The calling process must have previously acquired the lock
or queued the lock request by calling the Enqueue Lock Request
($ENQ) service.
The $DEQ, $ENQ, $ENQW (Enqueue Lock Request and Wait), and $GETLKI
(Get Lock Information) services together provide the user interface
to the VMS lock management facility.
Format:
SYS$DEQ [lkid] [,valblk] [,acmode] [,flags]
Arguments:
lkid
VMS usage: lock_id
type: longword (unsigned)
access: read only
mechanism: by value
Lock identification of the lock to be dequeued. The lkid argument
specifies this lock identification.
valblk
VMS usage: lock_value_block
type: longword (unsigned)
access: modify
mechanism: by reference
Lock value block for the resource associated with the lock to be
dequeued. The valblk argument is the address of the 16-byte lock
value block. This argument is not used when the LCK$M_DEQALL flag
is specified.
acmode
VMS usage: access_mode
type: longword (unsigned)
access: read only
mechanism: by value
Access mode of the lock to be dequeued. The acmode argument is a
longword containing the access mode.
flags
VMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by value
Flags specifying options for the $DEQ operation. The flags argument
is a longword bit mask that is the logical OR of each bit set, where
each bit corresponds to an option.
$DEVICE_SCAN
The Device Scan system service returns the names of all devices that
match a specified set of search criteria. The names returned by
$DEVICE_SCAN can then be passed to another service, for example,
$GETDVI or $MOUNT.
Format
SYS$DEVICE_SCAN return_devnam ,retlen ,[search_devnam]
,[itmlst] ,[contxt]
Arguments
return_devnam
VMS Usage: char_string
type: character-coded text string
access: write only
mechanism: by descriptor-fixed length string descriptor
Buffer to receive the device name. The return_devnam argument is the
address of a character string descriptor pointing to a buffer into
which $DEVICE_SCAN writes the name of the first or next device that
matches the specified search criteria. The maximum size of any
device name is 64 bytes.
retlen
VMS Usage: word_unsigned
type: word (unsigned)
access: write only
mechanism: by reference
Length of the device name string returned by $DEVICE_SCAN. The
retlen argument is the address of a word into which $DEVICE_SCAN
writes the length of the device name string.
search_devnam
VMS Usage: device_name
type: character-coded text string
access: read only
mechanism: by descriptor-fixed length string descriptor
Name of the device for which $DEVICE_SCAN is to search. The
search_devnam argument accepts the standard wildcard characters, the
asterisk (*), which matches any sequence of characters, and the
percent sign (%), which matches any one character. For example, to
match all unit 0 DU devices on any controller, specify *DU%0. This
string is compared to the most complete device name
(DVI$_ALLDEVNAM).
itmlst
VMS Usage: item_list_3
type: longword_unsigned
access: read only
mechanism: by reference
Item list specifying search criteria used to identify the device
names for return by $DEVICE_SCAN. The itmlst argument is the address
of a list of item descriptors, each of which describes one search
criterion. The list of item descriptors is terminated by a longword
of 0.
contxt
VMS Usage: quadword_unsigned
type: quadword (unsigned)
access: modify
mechanism: by reference
Value used to indicate the current position of a $DEVICE_SCAN
search. The contxt argument is the address of the quadword that
receives this information. On the initial call, the quadword should
contain 0.
$DGBLSC
The Delete Global Section service marks an existing permanent global
section for deletion. The actual deletion of the global section
takes place when all processes that have mapped the global section
have deleted the mapped pages.
Format:
SYS$DGBLSC [flags] ,gsdnam ,[ident]
Arguments:
flags
VMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by value
Mask indicating global section characteristics. The flags argument
is a longword value. A value of 0 (the default) specifies a group
global section; a value of SEC$M_SYSGBL specifies a system global
section.
gsdnam
VMS usage: section_name
type: character-coded text string
access: read only
mechanism: by descriptor--fixed
length string descriptor
Name of the global section to be deleted. The gsdnam is the address
of a character string descriptor pointing to this name string.
ident
VMS usage: section_id
type: quadword (unsigned)
access: read only
mechanism: by reference
Identification value specifying the version number of the global
section to be deleted and the matching criteria to be applied. The
ident argument is the address of a quadword structure containing
three fields.
$DISMOU
The Dismount Volume service dismounts a mounted volume or volume
sets.
Format:
SYS$DISMOU devnam ,[flags]
Arguments:
devnam
VMS usage: device_name
type: character-coded text string
access: read only
mechanism: by descriptor--fixed
length string descriptor
Device name of the device to be dismounted. The devnam argument is
the address of a character string descriptor pointing to the device
name string. The string may be either a physical device name or a
logical name. If it is a logical name, it must translate to a
physical device name.
flags
VMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by value
A longword bit vector specifying options for the dismount operation.
The flags argument is a longword bit vector wherein a bit, when set,
selects the corresponding option. Each bit has a symbolic name;
these names are defined by the $DMTDEF macro.
$DLCEFC
The Delete Common Event Flag Cluster service marks a permanent
common event flag cluster for deletion. The cluster is actually
deleted when no more processes are associated with it.
Format:
SYS$DLCEFC name
Argument
name
VMS usage: ef_cluster_name
type: character-coded text string
access: read only
mechanism: by descriptor--fixed
length string descriptor
Name of the common event flag cluster to be deleted. The name
argument is the address of a character string descriptor pointing to
the name of the cluster.
$DNS
The Distributed Name Service clerk service is the programming
interface to the VAX Distributed Name Service.
The $DNS service completes asynchronously; that is, it returns to
the client immediately after making a name service call. The status
returned to the client call indicates whether a request was
successfully queued to the name service.
The $DNSW call is the synchronous equivalent of $DNS. $DNSW is
identical to $DNS in every way except that $DNSW returns to the
caller after the operation completes.
Format
SYS$DNS [efn] ,func ,itmlst ,[dnsb] ,[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 $DNS completes. The efn
argument is a longword containing this number. The efn argument is
optional; if not specified, event flag 0 is set.
When $DNS begins execution, it clears the event flag. Even if the
service encounters an error and completes without queuing a name
service request, the specified event flag is set.
func
VMS Usage: function_code
type: longword (unsigned)
access: read only
mechanism: by value
Function code specifying the action that $DNS is to perform. The
func argument is a longword containing this function code.
A single call to $DNS can specify one function code. Most function
codes require or allow for additional information to be passed in
the call with the itmlst argument.
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 is three longwords. The descriptors can
be in any order in the item list. Each item descriptor specifies an
item code. Each item code either describes the specific information
to be returned by $DNS or otherwise affects the action designated by
the function code. The item list is terminated by a longword of 0.
dnsb
VMS Usage: dns_status_block
type: quadword (unsigned)
access: write only
mechanism: by reference
Status block to receive the final completion status of the $DNS
operation. The dnsb argument is the address of the quadword $DNS
status block.
The following diagram depicts the structure of a $DNS status block:
31 0
|-------------------------------------|
| return status |
|-------------------------------------|
| qualifying status |
|-------------------------------------|
astadr
VMS Usage: ast_procedure
type: procedure entry mask
access: call without stack unwinding
mechanism: by reference
Asynchronous system trap routine to be executed when I/O completes.
The astadr argument, which is the address of a longword value, is
the entry mask to the AST routine.
The AST routine executes in the access mode of the caller of $DNS.
astprm
VMS Usage: user_arg
type: longword (unsigned)
access: read only
mechanism: by value
Asynchronous system trap parameter passed to the AST service
routine. The astprm argument is a longword value containing the AST
parameter.
$DNSW
The Distributed Name Service clerk is the client interface to the
VAX Distributed Name Service.
The $DNSW service completes synchronously; that is, it returns to
the caller after the operation completes.
For asynchronous completion, use the $DNS service, which returns to
the caller immediately after making a name service call. The return
status to the client call indicates whether a request was
successfully queued to the name service.
In all other respects, $DNSW is identical to $DNS. Refer to the $DNS
description for complete information about the $DNSW service.
Format
SYS$DNSW [efn] ,func ,itmlst ,[dnsb] ,[astadr] ,[astprm]
$END_RU
Applicable only if you have the RMS Journaling option. See the VAX
RMS Journaling Manual.
The End Recovery Unit Service denotes the end of a recovery unit in
applications that use RMS Journaling. Use the $END_RU service when
you reach the end of a transaction (or other logical point in the
course of an application where data integrity would not be
compromised in the event of a system crash). The $END_RU service is
actually a combination of two other recovery unit services,
$PREPARE_RU and $COMMIT_RU. When you use $COMMIT_RU, the recovery
unit is terminated, and the records that were modified within the
recovery unit are available for further processing.
Format:
SYS$END_RU ru_handle
Arguments:
ru_handle
VMS Usage: ru_handle
type: longword (unsigned)
access: read only
mechanism: by reference
The ru_handle argument is the address of an unsigned longword that
contains the recovery unit handle returned by the $START_RU system
service.
$END_TRANS
Commits a 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 sets the event
flag to 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.
$END_TRANS Operation Flag
Flag Description
DDTM$M_SYNC Indicates successful synchronous completions 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.
If you specify astadr, the AST routine executes at the same access
mode as the caller of the $END_TRANS service.
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) structure that
designates the transaction to be committed. The default value
for this parameter is the current transaction.
$END_TRANSW
Commits a given transaction. It returns a failure status (SS$_
ABORT) if an error occurs that makes it impossible the transaction
to be committed.
$END_TRANSW completes synchronously; that is, it returns to the
caller after the request has actually completed.
For asynchronous completion, you use the End Transaction
($END_TRANS) system service; $END_TRANS commits a transaction
and allocates a transaction identifier without waiting for the
operation to complete.
In all other respects, $END_TRANSW is identical to $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]
$ENQ
The Enqueue Lock Request service queues a new lock or lock
conversion on a resource.
The $ENQ service completes asynchronously; that is, it returns to
the caller after queueing the lock request, without waiting for the
lock to be either granted or converted.
For synchronous completion, use the Enqueue Lock Request and Wait
($ENQW) service. The $ENQW service is identical to the $ENQ service
in every way except that $ENQW returns to the caller when the lock
is either granted or converted.
The $ENQ, $ENQW, $DEQ (Dequeue Lock Request), and $GETLKI (Get Lock
Information) services together provide the user interface to the
VMS lock management facility.
Format:
SYS$ENQ [efn] ,lkmode ,lksb [,flags] [,resnam]
[,parid] [,astadr] [,astprm] [,blkast]
[,acmode] [,nullarg]
Arguments:
efn
VMS usage: ef_number
type: longword (unsigned)
access: read only
mechanism: by value
Number of the event flag to be set when the lock request has been
granted. The efn argument is a longword containing this number.
lkmode
VMS usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by value
Lock mode requested. The lkmode argument is a longword specifying
this lock mode.
lksb
VMS usage: lock_status_block
type: longword (unsigned)
access: write only
mechanism: by reference
Lock status block in which $ENQ writes the final completion status
of the operation. The lksb argument is the address of the 8-byte
lock status block.
flags
VMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by value
Flags specifying options for the $ENQ operation. The flags argument
is a longword bit mask that is the logical OR of each bit set, where
each bit corresponds to an option.
resnam
VMS usage: char_string
type: character-coded text string
access: read only
mechanism: by descriptor--fixed
length string descriptor
Name of the resource to be locked by this lock. The resnam argument
is the address of a character string descriptor pointing to this
name. The name string may be from 1 to 31 bytes in length.
parid
VMS usage: lock_id
type: longword (unsigned)
access: read only
mechanism: by value
Lock identification of the parent lock. The parid argument is a
longword containing this identification value.
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 lock is either granted
or converted. 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 routine specified by the
astadr argument. The astprm argument specifies this longword
parameter.
blkast
VMS usage: ast_procedure
type: procedure entry mask
access: call without stack
unwinding
mechanism: by reference
Blocking AST routine to be called whenever this lock is granted and
is blocking any other lock requests. The blkast argument is the
address of the entry mask to this routine.
acmode
VMS usage: access_mode
type: longword (unsigned)
access: read only
mechanism: by value
Access mode to be associated with the lock. The acmode argument is
a longword containing the access mode.
nullarg
VMS usage: null_arg
type: longword (unsigned)
access: read only
mechanism: by value
Place-holding argument. This argument is reserved to DIGITAL.
$ENQW
The Enqueue Lock Request and Wait service queues a lock on a
resource.
The $ENQW service completes synchronously; that is, it returns to
the caller when the lock has been either granted or converted.
For asynchronous completion, use the Enqueue Lock Request ($ENQ)
service; $ENQ returns to the caller after queueing the lock request,
without waiting for the lock to be either granted or converted.
In all other respects, $ENQW is identical to $ENQ. Refer to the
documentation of $ENQ for all other information about the $ENQW
service.
The $ENQ, $ENQW, $DEQ (Dequeue Lock Request), and $GETLKI (Get Lock
Information) services together provide the user interface to the
VMS lock management facility.
Format:
SYS$ENQW [efn] ,lkmode ,lksb [,flags] [,resnam] [,parid]
[,astadr] [,astprm] [,blkast] [,acmode] [,nullarg]
$ERAPAT
The Get Security Erase Pattern service generates a security erase
pattern. A user-written erase routine can then write this pattern
into areas of memory containing sensitive data that is no longer in
use to prevent the inadvertent disclosure of the sensitive data.
Format:
SYS$ERAPAT [type] ,[count] ,[patadr]
Arguments:
type
VMS usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by value
Type of storage to be written over with the erase pattern. The type
argument is a longword containing the type of storage.
count
VMS usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by value
The number of times that $ERAPAT has been called in a single
security erase operation. The count argument is a longword
containing the iteration count.
patadr
VMS usage: longword_unsigned
type: longword (unsigned)
access: write only
mechanism: by reference
The security erase pattern to be written. The patadr is the address
of a longword into which the security erase pattern is to be
written.
$EXIT
The Exit service is used by the operating system to initiate image
run-down when the current image in a process completes execution.
Control normally returns to the command interpreter.
Format:
SYS$EXIT [code]
Argument
code
VMS usage: cond_value
type: longword (unsigned)
access: read only
mechanism: by value
Longword value to be saved in the process header as the completion
status of the current image. If not specified in a macro call, a
value of 1 is passed as the completion code for VAX MACRO and VAX
BLISS-32 and, a value of 0 is passed for other languages. This
value can be tested at the command level to provide conditional
command execution.
$EXPREG
The Expand Program/Control Region service adds a specified number of
new virtual pages to a process's program region or control region
for the execution of the current image. Expansion occurs at the
current end of that region's virtual address space.
Format:
SYS$EXPREG pagcnt ,[retadr] ,[acmode] ,[region]
Arguments:
pagcnt
VMS usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by value
Number of pages to add to the current end of the program or control
region. The pagcnt argument is a longword value containing this
number.
retadr
VMS usage: address_range
type: longword (unsigned)
access: write only
mechanism: by reference
Starting and ending process virtual addresses of the pages that
$EXPREG has actually added. The retadr is the address of a
two-longword array containing, in order, the starting and ending
process virtual addresses.
acmode
VMS usage: access_mode
type: longword (unsigned)
access: read only
mechanism: by value
Access mode to be associated with the newly added pages. The acmode
argument is a longword containing the access mode.
region
VMS usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by value
Number specifying which program region is to be expanded. The
region argument is a longword value. A value of 0 (the default)
specifies that the program region (P0 region) is to be expanded. A
value of 1 specifies that the control region (P1 region) is to be
expanded.
$FAO
The Formatted ASCII Output service (1) converts a binary value into
an ASCII character string in decimal, hexadecimal, or octal notation
and returns the character string in an output string and (2) inserts
variable character string data into an output string.
The Formatted ASCII Output with List Parameter ($FAOL) service
provides an alternate way to specify input parameters for a call to
the $FAO system service. The formats for both $FAO and $FAOL appear
below.
Format:
SYS$FAO ctrstr ,[outlen] ,outbuf ,[p1]...[Pn]
SYS$FAOL ctrstr ,[outlen] ,outbuf [,prmlst]
Arguments:
ctrstr
VMS usage: char_string
type: character-coded text string
access: read only
mechanism: by descriptor--fixed
length string descriptor
Control string passed to $FAO. The ctrstr argument is the address
of a character string descriptor pointing to the control string.
Refer to the online help for the F$FAO lexical function for a
summary of FAO directives (HELP LEXICALS F$FAO).
outlen
VMS usage: word_unsigned
type: word (unsigned)
access: write only
mechanism: by reference
Length in bytes of the fully formatted output string returned by
$FAO. The outlen argument is the address of a word containing this
value.
outbuf
VMS usage: char_string
type: character-coded text string
access: write only
mechanism: by descriptor--fixed
length string descriptor
Output buffer into which $FAO writes the fully formatted output
string. The outbuf argument is the address of a character string
descriptor pointing to the output buffer.
p1 to pn
VMS usage: varying_arg
type: longword (unsigned)
access: read only
mechanism: by value
FAO directive parameter(s). The p1 argument is a longword
containing the parameter needed by the first FAO directive
encountered in the control string, the p2 argument is a longword
containing the parameter needed for the second FAO directive, and so
on for the remaining arguments up to and including p20. If an FAO
directive does not require a parameter, that FAO directive is
processed without reading a parameter from the argument list.
prmlst
VMS usage: vector_longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by
reference
List of FAO directive parameters to be passed to the $FAOL service.
The prmlst argument is the address of a list of longwords wherein
each longword is a parameter. $FAOL processes these parameters
sequentially as it encounters, in the control string, FAO directives
that require parameters.
$FILESCAN
The Scan String for File Specification service searches a string for
a file specification and parses the components of that file
specification.
Format:
SYS$FILESCAN srcstr ,valuelst ,[fldflags]
Arguments:
srcstr
VMS usage: char_string
type: character-coded text string
access: read only
mechanism: by descriptor--fixed
length string descriptor
String to be searched for the file specification. The srcstr
argument is the address of a descriptor pointing to this string.
valuelst
VMS usage: item_list_2
type: longword (unsigned)
access: modify
mechanism: by reference
Item list specifying which components of the file specification are
to be returned by $FILESCAN; the components are the node, device,
directory, file name, file type and version number. The itmlst
argument is the address of a list of item descriptors wherein each
item descriptor specifies one component. The list of item
descriptors is terminated by a longword of 0.
fldflags
VMS usage: mask_longword
type: longword (unsigned)
access: write only
mechanism: by reference
Longword flag mask in which $FILESCAN sets a bit for each file
specification component found in the input string. The fldflags
argument is the address of this longword flag mask.
$FIND_HELD
The Find Identifiers Held by User service returns the identifier(s)
held by a specified holder. When called repeatedly with a context
longword, it returns in succession all the identifiers held by the
specified holder.
Format:
SYS$FIND_HELD holder ,[id] ,[attrib] ,[contxt]
Arguments:
holder
VMS usage: rights_holder
type: quadword (unsigned)
access: read only
mechanism: by reference
Holder whose identifier(s) are to be found when $FIND_HELD completes
execution. The holder argument is the address of a quadword data
structure containing the holder identifier. This quadword data
structure consists of a longword containing the holder UIC, followed
by a longword containing the value zero.
id
VMS usage: rights_id
type: longword (unsigned)
access: write only
mechanism: by reference
Identifier value found when $FIND_HELD completes execution. The id
argument is the address of a longword containing the identifier
value with which the holder is associated.
attrib
VMS usage: mask_longword
type: longword (unsigned)
access: write only
mechanism: by reference
Attributes associated with the identifier returned in id when the
$ADD_HOLDER completes execution. The attrib argument is the address
of a longword containing a bitmask specifying the attributes.
contxt
VMS usage: context
type: longword (unsigned)
access: modify
mechanism: by reference
Context value used when repeatedly calling $FIND_HELD. The contxt
argument is the address of a longword used while searching for all
identifiers. The context value must be initialized to zero, and the
resulting context of each call to $FIND_HELD must be presented to
each subsequent call. Once contxt has been passed to SYS$FIND_HELD,
do not modify its value.
$FIND_HOLDER
The Find Holder of Identifier service returns the holder of a
specified identifier. When called repeatedly with a context
longword, it returns all the holders of the specified identifier in
the order in which they were added.
Format:
SYS$FIND_HOLDER id ,[holder] ,[attrib] ,[contxt]
Arguments:
id
VMS usage: rights_id
type: longword (unsigned)
access: read only
mechanism: by value
Binary identifier value whose holder(s) is found by $FIND_HOLDER.
The id argument is a longword containing the binary identifier
value.
holder
VMS usage: rights_holder
type: quadword (unsigned)
access: write only
mechanism: by reference
Holder identifier returned when $FIND_HOLDER completes execution.
The holder argument is the address of a quadword containing the
holder identifier. The first longword contains the UIC of the
holder with the high-order word containing the group number and the
low-order word containing the member number. The second longword
contains the value zero.
attrib
VMS usage: mask_longword
type: longword (unsigned)
access: write only
mechanism: by reference
Mask of attributes associated with the holder record specified by
holder. The attrib argument is the address of a longword containing
the attribute mask.
contxt
VMS usage: context
type: longword (unsigned)
access: modify
mechanism: by reference
Context value used while searching for all the holders of the
specified identifier when executing $FIND_HOLDER. The contxt
argument is the address of a longword containing the context value.
When calling $FIND_HOLDER repeatedly, contxt must be set initially
to zero and the resulting context of each call to $FIND_HOLDER must
be presented to each subsequent call. Once the argument has been
passed to SYS$FIND_HOLDER, do not modify its value.
$FINISH_RDB
The Terminate Rights Database Context service deallocates the record
stream and clears the context value used with $FIND_HELD,
$FIND_HOLDER, or $IDTOASC.
Format:
SYS$FINISH_RDB contxt
Arguments:
contxt
VMS usage: context
type: longword (unsigned)
access: modify
mechanism: by reference
Context value to be cleared when $FINISH_RDB completes execution.
The contxt argument is a longword containing the address of the
context value.
$FORCEX
The Force Exit system service causes an Exit ($EXIT) service call to
be issued on behalf of a specified process.
Format:
SYS$FORCEX [pidadr] ,[prcnam] ,[code]
Arguments:
pidadr
VMS usage: process_id
type: longword (unsigned)
access: modify
mechanism: by reference
Process identification (PID) of the process to be forced to exit.
The pidadr argument is the address of a longword containing the PID.
prcnam
VMS usage: process_name
type: character-coded text string
access: read only
mechanism: by descriptor--fixed
length string descriptor
Process name of the process that is to be forced to exit. The
prcnam argument is the address of a character string descriptor
pointing to a 1- to 15-character process name string.
code
VMS usage: cond_value
type: longword (unsigned)
access: read only
mechanism: by value
Completion code value to be used as the exit parameter. The code
argument is a longword containing this value. If code is not
specified, a value of 0 is passed as the completion code.
$FORMAT_ACL
The Format Access Control List Entry service formats the specified
ACL entry (ACE) into a text string.
Format:
SYS$FORMAT_ACL aclent ,[acllen] ,aclstr ,[width] ,[trmdsc]
,[indent] ,[accnam] ,[nullarg] ,[nullarg]
Arguments:
aclent
VMS usage: char_string
type: character-coded text string
access: read only
mechanism: by descriptor--fixed
length string descriptor
Description of the ACE formatted when $FORMAT_ACL completes
execution. The aclent argument is the address of a descriptor
pointing to a buffer containing the description of the input ACE.
The first byte of the buffer contains the length of the ACE; the
second byte contains a value that identifies the type of ACE, which
in turn determines the ACE format.
acllen
VMS usage: word_unsigned
type: word (unsigned)
access: write only
mechanism: by reference
Length of the output string resulting when $FORMAT_ACL completes
execution. The acllen argument is the address of a word containing
the number of characters written to aclstr.
aclstr
VMS usage: char_string
type: character-coded text string
access: write only
mechanism: by descriptor--fixed
length string descriptor
Formatted ACE resulting when $FORMAT_ACL completes its execution.
The aclstr argument is the address of a string descriptor pointing
to a buffer containing the output string.
width
VMS usage: word_unsigned
type: word (unsigned)
access: read only
mechanism: by reference
Maximum width of the formatted ACE resulting when $FORMAT_ACL
completes its execution. The width argument is the address of a
word containing the maximum width of the formatted ACE. If this
argument is omitted or contains zero, an infinite length display
line is assumed. When the width is exceeded, the character
specified by trmdsc is inserted.
trmdsc
VMS usage: char_string
type: character-coded text string
access: read only
mechanism: by descriptor--fixed
length string descriptor
Line termination character(s) used in the formatted ACE. The trmdsc
argument is the address of a descriptor pointing to character string
containing the termination character(s) for each formatted ACE that
are inserted when the width has been exceeded.
indent
VMS usage: word_unsigned
type: word (unsigned)
access: read only
mechanism: by reference
Number of blank characters beginning each line of the formatted ACE.
The indent argument is the address of a word containing the number
of blank characters you want inserted at the beginning of each
formatted ACE.
accnam
VMS usage: access_bit_names
type: longword (unsigned)
access: read only
mechanism: by reference
Names of the bits in the access mask when executing the $FORMAT_ACL.
The accnam argument is the address of an array of 32 quadword
descriptors that define the names of the bits in the access mask.
Each element points to the name of a bit. The first element names
bit 0, the second element names bit 1 and so on.
nullarg
VMS usage: null_arg
type: longword (unsigned)
access: read only
mechanism: by value
Place-holding argument. This argument is reserved to DIGITAL.
$FORMAT_AUDIT
Converts a security auditing event message from binary format
to ASCII text and filters information the user considers too
sensitive to display.
Format:
SYS$FORMAT_AUDIT
[fmttyp] ,audmsg ,[outlen] ,[outbuf] ,[width] ,[trmdsc]
,[routin] [,fmtflg]
Arguments
fmttyp
VMS Usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by value
Format for the message. The fmttyp argument is a value indicating
whether the security audit message should be in brief format,
which is one line of information, or full format. The default
is full format. See the VMS Audit Analysis Utility Manual for
examples of formatted output.
audmsg
VMS Usage: char_string
type: character-coded text string
access: read only
mechanism: by descriptor
Security auditing message to format. The audmsg argument is the
address of a character descriptor pointing to a buffer containing
the binary message that requires formatting.
outlen
VMS Usage: word_unsigned
type: word (unsigned)
access: write only
mechanism: by reference
Length of the formatted security audit message. The outlen
argument is the address of the word receiving the final length
of the ASCII message.
outbuf
VMS Usage: char_string
type: character-coded text string
access: read only
mechanism: by descriptor
Buffer holding the formatted message. The outbuf argument is
the address of a descriptor pointing to the buffer receiving the
message.
width
VMS Usage: word_unsigned
type: word (unsigned)
access: read only
mechanism: by reference
Maximum width of the formatted message. The width argument is the
address of a word containing the line width value. The default is
80 columns.
trmdsc
VMS Usage: char_string
type: character-coded text string
access: read only
mechanism: by descriptor
Line termination characters used in a full format message. The
trmdsc argument is the address of a descriptor pointing to the
line termination characters to insert within a line segment
whenever the width is reached.
routin
VMS Usage: longword_unsigned
type: procedure
access: read only
mechanism: by reference
Routine that writes a formatted line to the output buffer. The
routin argument is the address of a routine called each time a
line segment is formatted. The argument passed to the routine is
the address of a character string descriptor for the line segment.
This output routine is called twice: the first time to set up
column titles and the second time to pass the formatted event
message. By using this routine argument, a caller can gain control
at various points in the processing of an audit event message.
fmtflg
VMS Usage: longword (unsigned)
type: mask_longword
access: read only
mechanism: by value
Determines the formatting of certain kinds of audit messages.
The fmtflg argument is a mask specifying whether sensitive
information, such as passwords, should be displayed or column
titles built for messages in brief format. The following table
describes the significant bits:
Bit Value Description
0 1 Do not format sensitive information, for
example, passwords.
0 Format sensitive information.
1 1 Build a column title for messages in brief
format. (You must specfy a fmttyp of brief and
a routin argument.)
0 Do not build column titles.
$GETDVI
The Get Device/Volume Information service returns information about
an I/O device; this information consists of primary and secondary
device characteristics.
The $GETDVI service completes asynchronously; that is, it returns to
the caller after queuing the information request, without waiting
for the requested information to be returned.
For synchronous completion, use the Get Device/Volume Information
and Wait ($GETDVIW) service. The $GETDVIW service is identical to
the $GETDVI service in every way except that $GETDVIW returns to the
caller with the requested information.
Format:
SYS$GETDVI [efn] ,[chan] ,[devnam] ,itmlst [,iosb] [,astadr]
[,astprm] [,nullarg]
Arguments:
efn
VMS usage: ef_number
type: longword (unsigned)
access: read only
mechanism: by value
Number of the event flag to be set when $GETDVI returns the
requested information. The efn argument is a longword containing
this number.
chan
VMS usage: channel
type: word (unsigned)
access: read only
mechanism: by value
Number of the I/O channel assigned to the device about which
information is desired. The chan argument is a word containing this
number.
devnam
VMS usage: device_name
type: character-coded text string
access: read only
mechanism: by descriptor--fixed
length string descriptor
The name of the device about which $GETDVI is to return information.
The devnam argument is the address of a character string descriptor
pointing to this name string.
itmlst
VMS usage: item_list_3
type: longword (unsigned)
access: read only
mechanism: by reference
Item list specifying which information about the device is to be
returned. The itmlst argument is the address of a list of item
descriptors, each of which describes an item of information. The
list of item descriptors is terminated by a longword of 0.
iosb
VMS usage: io_status_block
type: quadword (unsigned)
access: write only
mechanism: by reference
I/O status block which is to receive the final completion status.
The iosb 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 $GETDVI completes. The
astadr 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 the longword parameter.
nullarg
VMS usage: null_arg
type: quadword (unsigned)
access: read only
mechanism: by reference
Place-holding argument. This argument is reserved to DIGITAL.
$GETDVIW
The Get Device/Volume Information and Wait service returns
information about an I/O device; this information consists of
primary and secondary device characteristics.
The $GETDVIW service completes synchronously; that is, it returns to
the caller with the requested information.
For asynchronous completion, use the Get Device/Volume Information
($GETDVI) service; $GETDVI returns to the caller after queueing the
information request, without waiting for the information to be
returned.
In all other respects, $GETDVIW is identical to $GETDVI. Refer to
the documentation of $GETDVI for all other information about the
$GETDVIW service.
Format:
SYS$GETDVIW [efn] ,[chan] ,[devnam] ,itmlst [,iosb] [,astadr]
[,astprm] [,nullarg]
$GETJPI
The Get Job/Process Information service returns information about
one or more processes on the system.
The $GETJPI service completes asynchronously; that is, it returns to
the caller after queuing the information request, without waiting
for the requested information to be returned.
For synchronous completion, use the Get Job/Process Information and
Wait ($GETJPIW) service. The $GETJPIW service is identical to the
$GETJPI service in every way except that $GETJPIW returns to the
caller with the requested information.
Format:
SYS$GETJPI [efn] ,[pidadr] ,[prcnam] ,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 $GETJPI returns the
requested information. The efn argument is a longword containing
this number.
pidadr
VMS usage: process_id
type: longword (unsigned)
access: modify
mechanism: by reference
Process identification (PID) of the process about which $GETJPI is
to return information. The pidadr argument is the address of a
longword containing the PID.
prcnam
VMS usage: process_name
type: character-coded text string
access: read only
mechanism: by descriptor--fixed
length string descriptor
Name of the process about which $GETJPI is to return information.
The prcnam argument is the address of a character string descriptor
pointing to this name string.
itmlst
VMS usage: item_list_3
type: longword (unsigned)
access: read only
mechanism: by reference
Item list specifying which information about the process(es) is to
be returned. The itmlst argument is the address of a list of item
descriptors, each of which describes an item of information. The
list of item descriptors is terminated by a longword of 0.
iosb
VMS usage: io_status_block
type: quadword (unsigned)
access: write only
mechanism: by reference
I/O status block which is to receive the final completion status.
The iosb 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 $GETJPI completes. The
astadr 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 the longword parameter.
$GETJPIW
The Get Job/Process Information and Wait service returns information
about one or more processes on the system.
The $GETJPIW service completes synchronously; that is, it returns to
the caller with the requested information.
For asynchronous completion, use the Get Job/Process Information
($GETJPI) service; $GETJPI returns to the caller after queueing the
information request, without waiting for the information to be
returned.
In all other respects, $GETJPIW is identical to $GETJPI. Refer to
the documentation of $GETJPI for all other information about the
$GETJPIW service.
Format:
SYS$GETJPIW [efn] ,[pidadr] ,[prcnam] ,itmlst [,iosb]
[,astadr] [,astprm]
$GETLKI
The Get Lock Information service returns information about the lock
database on a VMS system.
The $GETLKI service completes asynchronously; that is, it returns to
the caller after queuing the information request, without waiting
for the information to be returned.
For synchronous completion, use the Get Lock Information and Wait
($GETLKIW) service; $GETLKIW returns to the caller with the
requested information. In all other respects, $GETLKIW is identical
to $GETLKI.
The $GETLKI, $GETLKIW, $ENQ (Enqueue Lock Request), $ENQW (Enqueue
Lock Request and Wait), and $DEQ (Dequeue Lock Request) services
together provide the user interface to the VMS lock management
facility.
Format:
SYS$GETLKI [efn] ,lkidadr ,itmlst [,iosb] [,astadr]
[,astprm] [,nullarg]
Arguments:
efn
VMS usage: ef_number
type: longword (unsigned)
access: read only
mechanism: by value
Number of the event flag to be set when $GETLKI completes. The efn
argument is a longword containing this number. If efn is not
specified, $GETLKI sets event flag 0.
lkidadr
VMS usage: lock_id
type: longword (unsigned)
access: modify
mechanism: by reference
Lock identification (lock id) for the lock about which information
is to be returned. The lock id is the second longword in the lock
status block, which was created when the lock was granted. The
lkidadr argument is the address of this longword.
itmlst
VMS usage: item_list_3
type: longword (unsigned)
access: read only
mechanism: by reference
Item list specifying the lock information that $GETLKI is to return.
The itmlst argument is the address of a list of item descriptors,
each of which describes an item of information. The list of item
descriptors is terminated by a longword of 0.
iosb
VMS usage: io_status_block
type: quadword (unsigned)
access: write only
mechanism: by reference
I/O Status Block that is to receive the final completion status.
The iosb argument is the address of a quadword.
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 service 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 the longword parameter.
nullarg
VMS usage: null_arg
type: longword (unsigned)
access: read only
mechanism: by value
Place-holding argument. This argument is reserved to DIGITAL.
$GETLKIW
The Get Lock Information and Wait service returns information about
the lock database on a VMS system.
The $GETLKIW service completes synchronously; that is, it returns to
the caller with the requested information.
For asynchronous completion, use the Get Lock Information ($GETLKI)
service; $GETLKI returns to the caller after queueing the
information request, without waiting for the information to be
returned.
In all other respects, $GETLKIW is identical to $GETLKI. Refer to
the documentation of $GETLKI for all other information about the
$GETLKIW service.
The $GETLKI, $GETLKIW, $ENQ (Enqueue Lock Request), $ENQW (Enqueue
Lock Request and Wait), and $DEQ (Dequeue Lock Request) services
together provide the user interface to the VMS lock management
facility.
Format:
SYS$GETLKIW [efn] ,lkidadr ,itmlst [,iosb] [,astadr] [,astprm]
[,nullarg]
$GETMSG
The Get Message service locates and returns message text associated
with a given message identification code into the caller's buffer.
The message can be from the system message file or can be a
user-defined message.
Format:
SYS$GETMSG msgid ,msglen ,bufadr ,[flags]
,[outadr]
Arguments:
msgid
VMS usage: cond_value
type: longword (unsigned)
access: read only
mechanism: by value
Identification of the message to be retrieved. The msgid argument
is a longword value containing the message identification. Each
message has a unique identification, contained in bits 3 through 27
of system longword condition values.
msglen
VMS usage: word_unsigned
type: word (unsigned)
access: write only
mechanism: by reference
Length of the message string returned by $GETMSG. The msglen
argument is the address of a word into which $GETMSG writes this
length.
bufadr
VMS usage: char_string
type: character-coded text string
access: write only
mechanism: by descriptor--fixed
length string descriptor
Buffer to receive the message string. The bufadr argument is the
address of a character string descriptor pointing to the buffer into
which $GETMSG writes the message string. The maximum size of any
message string is 256 bytes.
flags
VMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by value
Message components to be returned. The flags argument is a longword
bit vector, wherein a bit when set specifies that that message
component is to be returned.
outadr
VMS usage: vector_byte_unsigned
type: byte (unsigned)
access: write only
mechanism: by reference
Optional information to be returned by $GETMSG. The outadr is the
address of a four-byte array into which $GETMSG writes the following
information:
Byte Contents
0 Reserved
1 Count of FAO arguments associated with message
2 User-specified value in message, if any
3 Reserved
$GETQUI
The Get Queue Information ($GETQUI) service returns information
about queues and the jobs initiated from those queues. The $GETQUI
and $SNDJBC services together provide the user interface to the
VMS Job Controller, which is the VMS queue and accounting manager.
The $GETQUI service completes asynchronously; that is, it returns to
the caller after queuing the request, without waiting for the
operation to complete.
For synchronous completion, use the Get Queue Information and Wait
($GETQUIW) service. The $GETQUIW service is identical to $GETQUI in
every way except that $GETQUIW returns to the caller after the
operation has completed.
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. 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
Place-holding argument. This argument is reserved to 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 $GETQUI writes the completion status
after the requested operation has completed. The iosb 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
The Get Queue Information and Wait for Completion service ($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.
The $GETQUIW service completes synchronously; that is, it returns to
the caller with the requested information. For asynchronous
completion 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. Refer to
the documentation of $GETQUI for all other information about the
$GETQUIW service.
Format:
SYS$GETQUIW [efn] ,func [,nullarg] [,itmlst] [,iosb] [,astadr]
[,astprm]
$GETSYI
The Get SystemWide Information service returns information about the
local VAX system or about other VAX systems in a cluster.
For Version 5.0 of VMS, both the $GETSYI service and the Get
System-Wide Information and Wait ($GETSYIW) service complete
synchronously; that is, they return to the caller with the requested
information.
However, in the future, $GETSYI may be modified to complete
asynchronously; that is, it will return to the caller after queueing
the information request, without waiting for the information to be
returned. For this reason, DIGITAL recommends that you use the
$GETSYIW service for synchronous completion.
Format:
SYS$GETSYI [efn] ,[csidadr] ,[nodename] ,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 the $GETSYI request
completes. The efn argument is a longword containing this number.
csidadr
VMS usage: process_id
type: longword (unsigned)
access: modify
mechanism: by reference
Cluster system identification of the VAX node about which $GETSYI is
to return information. The csidadr is the address of a longword
containing this identification value.
nodename
VMS usage: process_name
type: character-coded text string
access: read only
mechanism: by descriptor--fixed
length string descriptor
Name of the VAX node about which $GETSYI is to return information.
The nodename argument is the address of a character string
descriptor pointing to this name string.
itmlst
VMS usage: item_list_3
type: longword (unsigned)
access: read only
mechanism: by reference
Item list specifying which information about the VAX node(s) is to
be returned. The itmlst argument is the address of a list of item
decriptors, each of which describes an item of information. The
list of item descriptors is terminated by a longword of 0.
iosb
VMS usage: io_status_block
type: quadword (unsigned)
access: write only
mechanism: by reference
I/O status block which is to receive the final completion status.
The iosb 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 $GETSYI completes. The
astadr 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 the longword parameter.
$GETSYIW
The Get System-Wide Information and Wait service returns information
about the local VAX system or about other VAX systems in a cluster.
For Version 5.0 of VMS, the $GETSYIW service is identical to the
Get System-Wide Information ($GETSYI) service. Both services return
the same information, and both complete synchronously; that is, they
return to the caller with the requested information.
However, in the future the $GETSYI service will be modified to
complete asynchronously; that is, it will return to the caller after
queueing the information request, without waiting for the
information to be returned. For this reason, DIGITAL recommends
that you use the $GETSYIW service for synchronous completion.
Refer to the documentation of $GETSYI for all other information
about the $GETSYIW service.
Format:
SYS$GETSYIW [efn] ,[csidadr] ,[nodename] ,itmlst [,iosb]
[,astadr] [,astprm]
$GETTIM
The Get Time service returns the current system time in 64-bit
format.
Format:
SYS$GETTIM timadr
Argument
timadr
VMS usage: date_time
type: quadword (unsigned)
access: write only
mechanism: by reference
Address of a quadword that is to receive the current time in 64-bit
format.
$GETUAI
The Get User Authorization Information ($GETUAI) service returns
authorization information about a specified user.
Format:
SYS$GETUAI [nullarg] ,[nullarg] ,usrnam ,itmlst ,[nullarg]
,[nullarg] ,[nullarg]
Arguments:
nullarg
VMS usage: null_arg
type: longword (unsigned)
access: read only
mechanism: by value
Place-holding argument. This argument is reserved to DIGITAL.
usrnam
VMS usage: char_string
type: character-coded text string
access: read only
mechanism: by
descriptor--fixed length string descriptor
Name of the user about whom $GETUAI returns authorization
information. The usrnam argument is the address of a descriptor
pointing to a character text string containing the user name. The
user name string may contain a maximum of 12 alphanumeric
characters.
itmlst
VMS usage: item_list_3
type: longword (unsigned)
access: read only
mechanism: by reference
Item list specifying which information from the specified user's UAF
(user authorization file) record is to be returned. The itmlst
argument is the address of a list 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.
$GRANTID
The Grant Identifier to Process service adds the specified
identifier record to the process' rights list or to the system
rights list. If the identifier is already in the rights list, the
attributes are modified as specified.
Format:
SYS$GRANTID [pidadr] ,[prcnam] ,[id] ,[name] ,[prvatr]
Arguments:
pidadr
VMS usage: process_id
type: longword (unsigned)
access: modify
mechanism: by reference
Process identification number (PID) of the process affected when
$GRANTID completes execution. The pidadr argument is the address of
longword containing the PID of process to be affected. Use --1 to
indicate the system rights list. When pidadr is passed, it is also
returned; therefore, you must pass it as a variable rather than a
constant. If neither pidadr nor prcnam is specified, your own
process is used.
prcnam
VMS usage: process_name
type: character-coded text string
access: read only
mechanism: by descriptor--fixed
length string descriptor
Process name on which $GRANTID operates. The prcnam argument is the
address of a character string descriptor containing the process
name. The maximum length of the name is 15 characters. Since the
UIC group number is interpreted as part of the process name, you
must use pidadr to specify the rights list of a process in a
different group. If neither pidadr nor prcnam is specified, your
own process is used.
id
VMS usage: rights_holder
type: quadword (unsigned)
access: modify
mechanism: by reference
Identifier and attributes to be granted when $GRANTID completes
execution. The id argument is the address of a quadword containing
the binary identifier code to be granted in the first longword and
the attributes in the second longword.
name
VMS usage: char_string
type: character-coded text string
access: read only
mechanism: by descriptor--fixed
length string descriptor
Name of the identifier granted when $GRANTID completes execution.
The name argument is the address of a descriptor pointing to the
name of the identifier. Either id or name must be specified.
prvatr
VMS usage: mask_longword
type: longword (unsigned)
access: write only
mechanism: by reference
Previous attributes of the identifier. The prvatr argument is the
address of a longword used to store the attributes of the identifier
if it was previously present in the rights list. If the identifier
was added rather than modified, prvatr is ignored.
$HASH_PASSWORD
Applies the hash algorithm you select to an ASCII password string
and returns a quadword hash value that represents the encrypted
password.
Format:
SYS$HASH_PASSWORD
pwd ,alg ,[salt] ,usrnam ,hash
Arguments
pwd
VMS Usage: char_string
type: character-coded text string
access: read only
mechanism: by descriptor-fixed-length string descriptor
ASCII password string to be encrypted. The pwd argument is the
address of a character string descriptor pointing to the ASCII
password. The password string can contain between 1 and 32
characters and use the uppercase characters A through Z, the
numbers 0 through 9, the dollar sign ($), and the underscore (_).
alg
VMS Usage: byte_unsigned
type: byte(unsigned)
access: read only
mechanism: by value
Algorithm used to hash the ASCII password string. The alg argument
is an unsigned byte specifying the hash algorithm. The VMS
operating system recognizes the following algorithms:
Symbolic Name Description
UAI$C_AD_II Uses a CRC algorithm and returns a longword
hash value. The algorithm was used in
releases prior to VMS Version 2.0.
UAI$C_PURDY Uses a Purdy algorithm over salted input.
It expects a blank-padded user name
and returns a quadword hash value. The
algorithm was used during VMS Version 2.0
field test.
UAI$C_PURDY_V Uses the Purdy algorithm over salted input.
It expects a variable length user name
and returns a quadword hash value. The
algorithm was used in releases prior to VMS
Version 5.4.
UAI$C_PURDY_S Uses the Purdy algorithm over salted input.
It expects a variable length user name
and returns a quadword hash value. The
algorithm is used to hash all new passwords
in VMS Version 5.4 and later.
UAI$C_PREFERED_ Represents the latest encryption algorithm
ALGORITHM that the VMS system uses to encrypt new
passwords. Currently, it equates to UAI$C_
PURDY_S. Digital recommends that you use
this symbol in source modules because it
will always equate with the most recent VMS
algorithm.
Values ranging from 128 to 256 are reserved for customer use; the
constant UAI$K_CUST_ALGORITHM defines the start of this range.
You can use the UAI$_ENCRYPT and UAI$_ENCRYPT2 item codes with
the $GETUAI system service to retrieve the primary and secondary
password hash algorithms for a user.
salt
VMS Usage: word_unsigned
type: word (unsigned)
access: read only
mechanism: by value
Value used to increase the effectiveness of the hash. The salt
argument is an unsigned word containing 16 bits of data that is
used by the hash algorithms when encrypting a password for the
associated user name. The $GETUAI item code UAI$_SALT is used to
retrieve the SALT value for a given user. If you do not specify a
SALT value, $HASH_PASSWORD uses the value of 0.
usrnam
VMS Usage: char_string
type: character-coded text string
access: read only
mechanism: by descriptor-fixed-length string descriptor
Name of the user associated with the password. The usrnam argument
is the address of a descriptor pointing to a character text string
containing the user name. The current VMS password encryption
algorithm (UAI$K_PURDY_S) folds the user name into the ASCII
password string to ensure that different users with the same
password produce different hash values. This argument must be
supplied for all calls to $HASH_PASSWORD but is ignored when using
the CRC algorithm (UAI$K_AD_II).
hash
VMS Usage: quadword_unsigned
type: quadword (unsigned)
access: write only
mechanism: by reference
Output hash value representing the encrypted password. The hash
argument is the address of an unsigned quadword to which $HASH_
PASSWORD writes the output of the hash. If you use the UAI$C_AD_II
algorithm, the second longword of the hash is always set to zero.
$HIBER
The Hibernate service allows a process to make itself inactive but
to remain known to the system so that it can be interrupted, for
example, to receive ASTs. A hibernate request is a
wait-for-wake-event request. When the Wake Process from Hibernation
($WAKE) service is called or when a Schedule Wakeup ($SCHDWK)
service comes due, the process continues execution at the
instruction following the Hibernate call.
Format:
SYS$HIBER
None
$IDTOASC
The Translate Identifier to Identifier Name service translates the
specified identifier value to its identifier name.
Format:
SYS$IDTOASC id ,[namlen] ,[nambuf] ,[resid] ,[attrib]
,[contxt]
Arguments:
id
VMS usage: rights_id
type: longword (unsigned)
access: read only
mechanism: by value
Binary identifier value translated by $IDTOASC. The id argument is
a longword containing the binary value of the identifier. To
determine the identifier names of all identifiers in the rights
database, specify id as --1 and call SYS$IDTOASC repeatedly until it
returns the status code SS$_NOSUCHID. The identifiers are returned
in alphabetical order.
namlen
VMS usage: word_unsigned
type: word (unsigned)
access: write only
mechanism: by reference
Number of characters in the identifier name translated by $IDTOASC.
The namlen argument is the address of a word containing the length
of the identifier name written to nambuf.
nambuf
VMS usage: char_string
type: character-coded text string
access: write only
mechanism: by descriptor--fixed
length string descriptor
Identifier name text string returned when $IDTOASC completes the
translation. The nambuf argument is the address of a descriptor
pointing to the buffer in which the identifier name is written.
resid
VMS usage: rights_id
type: longword (unsigned)
access: write only
mechanism: by reference
Identifier value of the identifier name returned in nambuf. The
resid argument is the address of a longword containing the 32-bit
code of the identifier.
attrib
VMS usage: mask_longword
type: longword (unsigned)
access: write only
mechanism: by reference
Mask of attributes associated with the identifier returned in resid.
The attrib argument is the address of a longword containing the
attribute mask.
contxt
VMS usage: context
type: longword (unsigned)
access: modify
mechanism: by reference
Context value used when repeatedly calling $IDTOASC. The contxt
argument is the address of a longword used while searching for all
identifiers. The context value must be initialized to zero, and the
resulting context of each call to $IDTOASC must be presented to each
subsequent call. Once contxt has been passed to $IDTOASC, do not
modify its value.
$LCKPAG
The Lock Pages In Memory service locks a page or range of pages in
memory. The specified virtual pages are forced into the working set
and then locked in memory. A locked page is not swapped out of
memory if its process's working set is swapped out. These pages are
not candidates for page replacement and in this sense are locked in
the working set as well.
Format:
SYS$LCKPAG inadr ,[retadr] ,[acmode]
Arguments:
inadr
VMS usage: address_range
type: longword (unsigned)
access: read only
mechanism: by reference
Starting and ending virtual addresses of the range of pages to be
locked. The inadr is the address of a two-longword array
containing, in order, the starting and the ending process virtual
addresses. Only the virtual page number portion of each virtual
address is used; the low-order 9 bits are ignored.
retadr
VMS usage: address_range
type: longword (unsigned)
access: write only
mechanism: by reference--array reference
or descriptor
Starting and ending process virtual addresses of the pages that
$LCKPAG actually locked. The retadr is the address of a
two-longword array containing, in order, the starting and ending
process virtual addresses.
acmode
VMS usage: access_mode
type: longword (unsigned)
access: read only
mechanism: by value
Access mode to be associated with the pages to be locked. The
acmode argument is a longword containing the access mode. The
$PSLDEF macro defines the four access modes.
$LKWSET
The Lock Pages in Working Set service locks a range of pages in the
working set; if the pages are not already in the working set, it
brings them in and locks them. A page that is locked in the working
set does not become a candidate for replacement.
Format:
SYS$LKWSET inadr ,[retadr] ,[acmode]
Arguments:
inadr
VMS usage: address_range
type: longword (unsigned)
access: read only
mechanism: by reference
Starting and ending virtual addresses of the range of pages to be
locked in the working set. The inadr is the address of a
two-longword array containing, in order, the starting and the ending
process virtual addresses. Only the virtual page number portion of
each virtual address is used; the low-order 9 bits are ignored.
retadr
VMS usage: address_range
type: longword (unsigned)
access: write only
mechanism: by reference
Starting and ending process virtual addresses of the range of pages
actually locked by $LCKWSET. The retadr is the address of a
two-longword array containing, in order, the starting and ending
process virtual addresses.
acmode
VMS usage: access_mode
type: longword (unsigned)
access: read only
mechanism: by value
Access mode to be associated with the pages to be locked. The
acmode argument is a longword containing the access mode. The
$PSLDEF macro defines the four access modes.
$MGBLSC
The Map Global Section service establishes a correspondence between
(maps) pages in the process's virtual address space and physical
pages occupied by a global section.
Format:
SYS$MGBLSC inadr ,[retadr] ,[acmode] ,[flags] ,gsdnam ,[ident]
,[relpag]
Arguments:
inadr
VMS usage: address_range
type: longword (unsigned)
access: read only
mechanism: by reference
Starting and ending virtual addresses in the process's virtual
address space (either the P0 or P1 regions) into which the section
is to be mapped. The inadr is the address of a two-longword array
containing, in order, the starting and the ending process virtual
addresses. Only the virtual page number portion of each virtual
address is used; the low-order 9 bits are ignored.
retadr
VMS usage: address_range
type: longword (unsigned)
access: write only
mechanism: by reference
Starting and ending process virtual addresses into which the section
was actually mapped by $MGBLSC. The retadr is the address of a
two-longword array containing, in order, the starting and ending
process virtual addresses.
acmode
VMS usage: access_mode
type: longword (unsigned)
access: read only
mechanism: by value
Access mode to be associated with the pages that are mapped into the
process virtual address space. The acmode argument is a longword
containing the access mode. The $PSLDEF macro defines symbols for
the four access modes.
flags
VMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by value
Flag mask specifying options for the operation. The flags argument
is a longword bit vector wherein a bit when set specifies the
corresponding option.
gsdnam
VMS usage: section_name
type: character-coded text string
access: read only
mechanism: by descriptor--fixed
length string descriptor
Name of the global section. The gsdnam argument is the address of a
character string descriptor pointing to this name string.
ident
VMS usage: section_id
type: quadword (unsigned)
access: read only
mechanism: by reference
Identification value specifying the version number of a global
section, and, for processes mapping to an existing global section,
the criteria for matching the identification. The ident argument is
the address of a quadword structure containing three fields.
relpag
VMS usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by value
Relative page number within the section of the first page to be
mapped. The relpag argument is a longword containing this number.
$MOD_HOLDER
The Modify Holder Record in Rights Database service modifies the
specified holder record of the target identifier in the rights
database. Identifier attributes may be added, or removed, or both.
Format:
SYS$MOD_HOLDER id ,holder ,[set_attrib] ,[clr_attrib]
Arguments:
id
VMS usage: rights_id
type: longword (unsigned)
access: read only
mechanism: by value
Binary value of target identifier whose holder record is modified
when $MOD_HOLDER completes execution. The id argument is a longword
containing the identifier value.
holder
VMS usage: rights_holder
type: quadword (unsigned)
access: read only
mechanism: by reference
Identifier of holder being modified when $MOD_HOLDER completes
execution. The holder argument is the address of a quadword
containing the UIC identifier of the holder in the first longword
and the value of zero in the second longword.
set_attrib
VMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by value
Bitmask of attributes to be enabled for the identifier when
$MOD_HOLDER completes execution. The set_attrib argument is a
longword containing the attribute mask.
clr_attrib
VMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by value
Bitmask of attributes to be disabled for the identifier when
$MOD_HOLDER completes execution. The clr_attrib argument is a
longword containing the attribute mask.
$MOD_IDENT
The Modify Identifier in Rights Database service modifies the
specified identifier record in the rights database. Identifier
attributes may be added, or removed, or both. The identifier name
or value may be changed.
Format:
SYS$MOD_IDENT id ,[set_attrib] ,[clr_attrib] ,[new_name]
,[new_value]
Arguments:
id
VMS usage: rights_id
type: longword (unsigned)
access: read only
mechanism: by value
Binary value of identifier whose identifier record is modified when
$MOD_IDENT completes execution. The id argument is a longword
containing the identifier value.
set_attrib
VMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by value
Bitmask of attributes to be enabled for the identifier when
$MOD_IDENT completes execution. The set_attrib argument is a
longword containing the attribute mask.
clr_attrib
VMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by value
Bitmask of attributes to be disabled for the identifier when
$MOD_IDENT completes execution. The clr_attrib argument is a
longword containing the attribute mask.
new_name
VMS usage: char_string
type: character-coded text string
access: read only
mechanism: by descriptor--fixed
length string descriptor
New name to be given to the specified identifier. The new_name
argument is the address of the descriptor pointing to the identifier
name string.
new_value
VMS usage: rights_id
type: longword (unsigned)
access: read only
mechanism: by value
New value to be assigned to the specified identifier. The new_value
argument is a longword containing the binary value of the specified
identifier. When the identifier value is changed, $MOD_IDENT also
changes the value of the identifier in all of the holder records in
which the specified identifier appears.
$MOUNT
The Mount Volume service mounts a tape, disk volume, or volume set
and specifies options for the mount operation.
Format:
SYS$MOUNT itmlst
Argument
itmlst
VMS usage: item_list_3
type: longword (unsigned)
access: read only
mechanism: by reference
Item list specifying options for the mount operation. The itmlst
argument is the address of a list of item descriptors, each of which
specifies an option and provides the information needed to perform
the operation.
$MTACCESS
The Magnetic Tape Accessibility service allows installations to
provide their own routine to interpret and output the accessibility
field in the VOL1 and HDR1 labels of an ANSI labeled magnetic tape.
(ANSI refers to the American National Standard for Magnetic Tape
Labels and File Structure for Information Interchange---ANSI,
x3.27-1978)
Format:
SYS$MTACCESS lblnam ,[uic] ,[std_version] ,[access_char]
,[access_spec] ,type
Arguments:
lblnam
VMS usage: address
type: longword (unsigned)
access: read only
mechanism: by reference
ANSI label to be processed. The lblnam argument is the address of a
longword containing the label. On input, the label passed is either
the VOL1 or HDR1 label read from the magnetic tape; on output of
labels, this field is zero. The type of label passed is determined
by type.
uic
VMS usage: uic
type: longword (unsigned)
access: read only
mechanism: by value
UIC of the user performing the operation. The uic argument is a
longword containing the UIC.
std_version
VMS usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by value
Decimal equivalent of the ANSI standard version read from the VOL1
label. The std_version argument is a longword containing the
standard version number.
access_char
VMS usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by value
Accessibility character specified by the user. The access_char
argument is a byte containing the accessibility character used for
the output of labels.
access_spec
VMS usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by value
Value specifying whether the accessibility character passed in
access_char was specified by the user.
type
VMS usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by value
Type of accessibility field to process.
$NUMTIM
The Convert Binary Time to Numeric Time service converts an absolute
or delta time from 64-bit system time format to binary integer date
and time values.
Format:
SYS$NUMTIM timbuf ,[timadr]
Arguments:
timbuf
VMS usage: vector_word_unsigned
type: word (unsigned)
access: write only
mechanism: by reference
Buffer into which $NUMTIM writes the converted date and time. The
numtim argument is the address of a 7-word structure.
timadr
VMS usage: date_time
type: quadword (unsigned)
access: read only
mechanism: by reference
The 64-bit time value to be converted. The timadr argument is the
address of a quadword containing this time. A positive time value
represents an absolute time, while a negative time value indicates a
delta time.
$PARSE_ACL
The Parse Access Control List Entry service parses the specified
text string and converts it into the binary representation for an
access control list entry (ACE).
Format:
SYS$PARSE_ACL aclstr ,aclent ,[errpos] ,[accnam]
,[nullarg] ,[nullarg]
Arguments:
aclstr
VMS usage: char_string
type: character-coded text string
access: read only
mechanism: by descriptor--fixed
length string descriptor
Formatted ACE that is parsed when $PARSE_ACL completes execution.
The aclstr argument is the address of a string descriptor pointing
to the text string to be parsed.
aclent
VMS usage: char_string
type: character-coded text string
access: write only
mechanism: by descriptor--fixed
length string descriptor
Description of the ACE that is parsed when $PARSE_ACL completes
execution. The aclent argument is the address of a descriptor
pointing to the buffer in which the ACE is written. The first byte
of the buffer contains the length of the ACE; the second byte
contains a value that identifies the type of ACE, which in turn
defines the format of the ACE. See the SYS$FORMAT_ACL service for
information on the ACE types and their associated formats.
errpos
VMS usage: word_unsigned
type: word (unsigned)
access: write only
mechanism: by reference
Number of characters from aclstr processed by SYS$PARSE_ACL. The
errpos argument is the address of a word that receives the number of
characters actually processed by the service. If the service fails,
this count points to the failing point in the string.
accnam
VMS usage: access_bit_names
type: longword (unsigned)
access: read only
mechanism: by reference
Names of the bits in the access mask when executing $PARSE_ACL. The
accnam argument is the address of an array of 32 quadword
descriptors that define the names of the bits in the access mask.
Each element points to the name of a bit. The first element names
bit 0, the second element names bit 1, and so on.
nullarg
VMS usage: null_arg
type: longword (unsigned)
access: read only
mechanism: by value
Place-holding argument. This argument is reserved to DIGITAL.
$PREPARE_RU
Applicable only if you have the RMS Journaling option. See the VAX
RMS Journaling Manual.
The Prepare Recovery Unit Service marks a point in the recovery unit
of an application using RMS Journaling where all modifications to
records within a recovery unit are complete. When you issue a call
to the $PREPARE_RU service, no further modifications are permitted
for any files that are connected to the recovery unit that was
started with the $START_RU call) until that recovery unit is no
longer active. After you issue a $PREPARE_RU call, the recovery unit
must be terminated with either a call to the $ABORT_RU service or
the $COMMIT_RU service.
Although you cannot modify any data between the $PREPARE_RU and
$COMMIT_RU calls or between the $PREPARE_RU and $ABORT_RU calls, you
can include other processing (such as data verification) to
determine whether you wish to commit or abort the recovery unit.
After using $PREPARE_RU, do not issue a call to the $END_RU service;
use $COMMIT_RU to end the recovery unit and retain the record
modifications that were made during the recovery unit.
Format:
SYS$PREPARE_RU ru_handle
Arguments:
ru_handle
VMS Usage: ru_handle
type: longword (unsigned)
access: read only
mechanism: by reference
The ru_handle argument is the address of an unsigned longword that
contains the recovery unit handle returned by the $START_RU system
service.
$PROCESS_SCAN
The Process Scan system service creates and initializes a process
context that is used by $GETJPI to scan processes on the local
system or across the nodes in a VAXcluster system. An item list is
used to specify selection criteria to obtain information about
specific processes, for example, all processes owned by one user or
all batch processes.
Format
SYS$PROCESS_SCAN pidctx [,itmlst]
Arguments
pidctx
VMS Usage: process_id
type: longword (unsigned)
access: modify
mechanism: by reference
Context value supplied by $PROCESS_SCAN to be used as the pidadr
argument of $GETJPI. The pidctx argument is the address of a
longword that is to receive the process context longword. This
longword normally contains zero or a previous context. If it
contains a previous context, the old context is deleted. If it
contains a value other than zero or a previous context, the old
value is ignored.
itmlst
VMS Usage: item_list_3
type: longword (unsigned)
access: read only
mechanism: by reference
Item list specifying selection criteria to be used by the scan or to
control the scan.
The itmlst argument is the address of a list of item descriptors,
each of which describes one selection criterion or control option.
Within each selection criterion you can include several item
entries. The list of item descriptors is terminated by a longword of
zero.
The information in the item list is passed to the item descriptor in
one of two ways. If the item descriptor can always hold the actual
value of the selection criterion, the value is placed in the second
longword of the item descriptor and the buffer length is specified
as zero. If the item descriptor points to the actual value of the
selection criterion, the address of the value is placed in the
second longword of the item descriptor and you must specify the
buffer length for the selection criterion. Each item code
description specifies whether the information is passed by value or
by reference.
$PURGWS
The Purge Working Set service removes a specified range of pages
from the calling process's current working set to make room for
pages required by a new program segment. However, the Adjust
Working Set Limit ($ADJWSL) service is the preferred mechanism for
controlling a process's use of physical memory resources.
Format:
SYS$PURGWS inadr
Argument
inadr
VMS usage: address_range
type: longword (unsigned)
access: read only
mechanism: by reference
Starting and ending virtual addresses of the range of pages to be
purged. The inadr is the address of a two-longword array
containing, in order, the starting and the ending process virtual
addresses. Only the virtual page number portion of each virtual
address is used; the low-order 9 bits are ignored.
$PUTMSG
The Put Message service is a generalized message-formatting and
output routine used by VMS to write informational and error messages
to processes. These messages are written to SYS$ERROR and
SYS$OUTPUT. Informational messages are written to SYS$OUTPUT only;
error messages are written to SYS$ERROR. Error messages are also
written to SYS$OUTPUT if it has a different definition from
SYS$ERROR.
Format:
SYS$PUTMSG msgvec ,[actrtn] ,[facnam] ,[actprm]
Arguments:
msgvec
VMS usage: cntrlblk
type: longword (unsigned)
access: read only
mechanism: by reference
Message argument vector specifying the message(s) to be written and
options that $PUTMSG is to use in writing the message(s). The
msgvec argument is the address of the message vector.
actrtn
VMS usage: procedure
type: procedure entry mask
access: call without stack unwinding
mechanism: by reference
User-supplied action routine to be executed during message
processing. The actrtn argument is the address of the entry mask of
this routine.
facnam
VMS usage: char_string
type: character-coded text string
access: read only
mechanism: by descriptor--fixed length string descriptor
Facility prefix to be used in the first or only message written by
$PUTMSG. The facnam argument is the address of a character string
descriptor pointing to this facility prefix.
If you do not specify facnam, $PUTMSG uses the default facility
prefix associated with the message.
actprm
VMS usage: user_arg
type: longword (unsigned)
access: read only
mechanism: by value
Parameter to be passed to the action routine. The actprm is a
longword value containing this parameter. If actprm is not
specified, no parameter is passed.
$QIO
The Queue I/O Request service queues an I/O request to a channel
associated with a device.
The $QIO service completes asynchronously; that is, it returns to
the caller immediately after queuing the I/O request, without
waiting for the I/O operation to complete.
For synchronous completion, use the Queue I/O Request and Wait
($QIOW) service. The $QIOW service is identical to the $QIO service
in every way except that $QIOW returns to the caller after the I/O
operation has completed.
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 actually
completes. The efn argument is a longword value containing the
number of the event flag.
chan
VMS usage: channel
type: word (unsigned)
access: read only
mechanism: by value
I/O channel that is assigned to the device to which the request is
directed. The chan argument is a word value containing the number
of the I/O channel; however, $QIO uses only the low-order word.
func
VMS usage: function_code
type: word (unsigned)
access: read only
mechanism: by value
Device-specific function codes and function modifiers specifying the
operation to be performed. The func is a longword value 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 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
Optional device- and function-specific I/O request parameters.
$QIOW
The Queue I/O Request and Wait service queues an I/O request to a
channel associated with a device.
The $QIOW service completes synchronously; that is, it returns to
the caller after the I/O operation has actually completed.
For asynchronous completion, use the Queue I/O Request ($QIO)
service; $QIO returns to the caller after queuing the I/O request,
without waiting for the I/O operation to be completed.
In all other respects, $QIOW is identical to $QIO. Refer to the
documentation of $QIO for all other information about the $QIOW
service.
Format:
SYS$QIOW [efn] ,chan ,func [,iosb] [,astadr] [,astprm]
[,p1] [,p2] [,p3] [,p4] [,p5] [,p6]
$READEF
The Read Event Flags service returns the current status of all 32
event flags in a local or common event flag cluster. In addition,
the condition value returned indicates whether the specified event
flag is set or clear.
Format:
SYS$READEF efn ,state
Arguments:
efn
VMS usage: ef_number
type: longword (unsigned)
access: read only
mechanism: by value
Number of any event flag in the cluster whose status is to be
returned. The efn argument is a longword containing this number.
Specifying an event flag within a cluster requests that $READEF
return the status of all event flags in that cluster.
state
VMS usage: mask_longword
type: longword (unsigned)
access: write only
mechanism: by reference
State of all event flags in the specified cluster. The state
argument is the address of a longword into which $READEF writes the
state (set or clear) of the 32 event flags in the cluster.
$RELEASE_VP
Terminates the current process's status as a vector consumer.
Format:
SYS$RELEASE_VP
Arguments
None.
$REM_HOLDER
Deletes the specified holder record from the target identifier's
list of holders.
Format:
SYS$REM_HOLDER id ,holder
Arguments:
id
VMS usage: rights_id
type: longword (unsigned)
access: read only
mechanism: by value
Binary value of target identifier whose holder is deleted when
$REM_HOLDER completes execution. The id argument is a longword
containing the identifier value.
holder
VMS usage: rights_holder
type: quadword (unsigned)
access: read only
mechanism: by reference
Identifier of holder being deleted when $REM_HOLDER completes
execution. The holder argument is the address of a quadword
containing the UIC identifier of the holder in the first longword
and the value of zero in the second longword.
$REM_IDENT
The Remove Identifier from Rights Database service removes the
specified identifier record and all its holder records (if any) from
the rights database.
Format:
SYS$REM_IDENT id
Arguments:
id
VMS usage: rights_id
type: longword (unsigned)
access: read only
mechanism: by value
Binary value of identifier deleted from rights database when
$REM_IDENT completes execution. The id argument is a longword
containing the identifier value.
$RESTORE_VP_EXCEPTION
Restores the saved exception state of the vector processor.
Format:
SYS$RESTORE_VP_EXCEPTION excid
Arguments
excid
VMS Usage: context
type: longword (unsigned)
access: read only
mechanism: by reference
Internal ID of the exception state saved by $SAVE_VP_EXCEPTION.
The excid argument is the address of a longword containing this
ID.
$RESTORE_VP_STATE
Allows an AST routine or condition handler to restore the vector
state of the mainline routine.
Format:
SYS$RESTORE_VP_STATE
Arguments
None.
$RESUME
The Resume Process service (1) causes a process previously suspended
by the Suspend Process ($SUSPND) service to resume execution or (2)
cancels the effect of a subsequent suspend request.
Format:
SYS$RESUME [pidadr] ,[prcnam]
Arguments:
pidadr
VMS usage: process_id
type: longword (unsigned)
access: modify
mechanism: by reference
Process identification (PID) of the process that is to be resumed.
The pidadr argument is the address of a longword containing the PID.
prcnam
VMS usage: process_name
type: character-coded text string
access: read only
mechanism: by descriptor--fixed
length string descriptor
Name of the process to be resumed. The prcnam is the address of a
character string descriptor pointing to the process name, which is a
character string of from 1 to 15 characters.
$REVOKID
The Revoke Identifier from Process service removes the specified
identifier from the process's rights list, or from the system rights
list. If the identifier is listed as a holder of any other
identifier, the appropriate holder records are also deleted.
Format:
SYS$REVOKID [pidadr] ,[prcnam] ,[id] ,[name]
,[prvatr]
Arguments:
pidadr
VMS usage: process_id
type: longword (unsigned)
access: modify
mechanism: by reference
Process identification number (PID) of the process affected when
$REVOKID completes execution. The pidadr argument is the address of
longword containing the PID of process to be affected. Use --1 to
indicate the system rights list. When pidadr is passed, it is also
returned; therefore, you must pass it as a variable rather than a
constant.
prcnam
VMS usage: process_name
type: character-coded text string
access: read only
mechanism: by descriptor--fixed
length string descriptor
Process name on which $REVOKID operates. The prcnam argument is the
address of a character string descriptor containing the process
name. The maximum length of the name is 15 characters. Since the
UIC group number is interpreted as part of the process name, you
must use pidadr to specify the rights list of a process in a
different group.
id
VMS usage: rights_id
type: quadword (unsigned)
access: modify
mechanism: by reference
Identifier and attributes to be removed when $REVOKID completes
execution. The id argument is the address of a quadword containing
the binary identifier code to be removed in the first longword and
the attributes in the second longword.
name
VMS usage: char_string
type: character-coded text string
access: read only
mechanism: by descriptor--fixed
length string descriptor
Name of the identifier removed when $REVOKID completes execution.
The name argument is the address of a descriptor pointing to the
name of the identifier.
prvatr
VMS usage: mask_longword
type: longword (unsigned)
access: write only
mechanism: by reference
Attributes of the deleted identifier. The prvatr argument is the
address of a longword used to store the attributes of the
identifier.
$SAVE_VP_EXCEPTION
Saves the pending exception state of the vector processor.
Format:
SYS$SAVE_VP_EXCEPTION excid
Arguments
excid
VMS Usage: context
type: longword (unsigned)
access: read only
mechanism: by reference
Internal ID of the exception state saved by $SAVE_VP_EXCEPTION.
The excid argument is the address of a longword containing this
ID.
$SCHDWK
The Schedule Wakeup service schedules the awakening of a process
that has placed itself in a state of hibernation with the Hibernate
($HIBER) service. A wakeup can be scheduled for a specified
absolute time or for a delta time, and can be repeated at fixed
intervals.
Format:
SYS$SCHDWK [pidadr] ,[prcnam] ,daytim ,[reptim]
Arguments:
pidadr
VMS usage: process_id
type: longword (unsigned)
access: modify
mechanism: by reference
Process identification (PID) of the process that is to be awakened.
The pidadr argument is the address of a longword containing the PID.
prcnam
VMS usage: process_name
type: character-coded text string
access: read only
mechanism: by descriptor--fixed
length string descriptor
Name of the process to be awakened. The prcnam is the address of a
character string descriptor pointing to the process name, which is a
character string of from 1 to 15 characters.
daytim
VMS usage: date_time
type: quadword (unsigned)
access: read only
mechanism: by reference
Time at which the process is to be awakened. The daytim argument is
the address of a quadword containing this time in the system 64-bit
time format. A positive time value specifies an absolute time at
which the specified process is to be awakened. A negative time
value specifies an offset (delta time) from the current time.
reptim
VMS usage: date_time
type: quadword (unsigned)
access: read only
mechanism: by reference
Time interval at which the wakeup request is to be repeated. The
reptim argument is the address of a quadword containing this time
interval. The time interval must be expressed in delta time format.
$SETAST
The Set AST Enable service enables or disables the delivery of ASTs
for the access mode from which the service call was issued.
Format:
SYS$SETAST enbflg
Argument
enbflg
VMS usage: boolean
type: byte (unsigned)
access: read only
mechanism: by value
Value specifying whether ASTs are to be enabled. The enbflg
argument is a byte containing this value. A value of 1 enables AST
delivery for the calling access mode; a value of 0 disables AST
delivery.
$SETEF
The Set Event Flag service sets an event flag in a local or common
event flag cluster. The condition value returned by $SETEF
indicates whether the specified flag was previously set or clear.
Once the event flag is set, processes waiting for the event flag to
be set resume execution.
Format:
SYS$SETEF efn
Argument
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.
$SETEXV
The Set Exception Vector service (1) assigns a condition handler
address to the primary, secondary, or last chance exception vectors
or (2) removes a previously assigned handler address from any of
these three vectors.
Format:
SYS$SETEXV [vector] ,[addres] ,[acmode] ,[prvhnd]
Arguments:
vector
VMS usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by value
Vector for which a condition handler is to be established or
removed. The vector argument is a longword value. A value of 0
(the default) specifies the primary vector; a value of 1, the
secondary vector; and a value of 2, the last chance exception
vector.
addres
VMS usage: procedure
type: procedure entry mask
access: call without stack unwinding
mechanism: by
reference
Condition handler address to be established for the exception vector
specified by vector. The addres argument is a longword value
containing the address of the entry mask to the condition handler
routine.
acmode
VMS usage: access_mode
type: longword (unsigned)
access: read only
mechanism: by value
Access mode for which the exception vector is to be modified. The
acmode argument is a longword containing the access mode. The
$PSLDEF macro defines symbols for the four access modes.
prvhnd
VMS usage: procedure
type: longword (unsigned)
access: write only
mechanism: by reference
Previous condition handler address contained by the specified
exception vector. The prvhnd argument is the address of a longword
into which $SETEF writes the handler address.
$SETIME
The Set System Time service (1) changes the value of or (2)
recalibrates the system time.
The system time is defined by a quadword value that specifies the
number of 100 nanosecond intervals since 00:00 o'clock, November 17,
1858.
The system time is the reference used for nearly all timer-related
software activities in VMS.
Format:
SYS$SETIME [timadr]
Argument
timadr
VMS usage: date_time
type: quadword (unsigned)
access: read only
mechanism: by reference
New time value for the system time. The timadr argument is the
address of a quadword containing the new system time value. The new
system time value is an absolute time value specifying the number of
100 nanosecond intervals since 00:00 o'clock, November 17, 1858. A
negative (delta) time value is invalid.
$SETIMR
The Set Timer service sets the timer to expire at a specified time.
When the timer expires, an event flag is set and (optionally) an AST
routine executes.
Format:
SYS$SETIMR [efn] ,daytim ,[astadr] ,[reqidt] ,[flags]
Arguments:
efn
VMS usage: ef_number
type: longword (unsigned)
access: read only
mechanism: by value
Event flag to be set when the timer expires. The efn argument is a
longword value containing the number of the event flag. If efn is
not specified, event flag 0 is set.
daytim
VMS usage: date_time
type: quadword (unsigned)
access: read only
mechanism: by reference
Time at which the timer expires. The daytim argument is the address
of a quadword time value. A positive time value specifies an
absolute time at which the timer expires; a negative time value
specifies an offset (delta time) from the current time.
astadr
VMS usage: ast_procedure
type: procedure entry mask
access: call without stack unwinding
mechanism: by
reference
AST service routine that is to execute when the timer expires. The
astadr is the address of the entry mask of this routine. If astadr
is not specified or is specified as 0 (the default), no AST routine
executes.
reqidt
VMS usage: user_arg
type: longword (unsigned)
access: read only
mechanism: by value
Identification of the timer request. The reqidt is a longword value
containing a number that uniquely identifies the timer request. If
reqidt is not specified, the value 0 is used.
flags
VMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by value
$SETPRA
The Set Power Recovery AST service establishes a routine to receive
control after a power recovery is detected.
Format:
SYS$SETPRA astadr ,[acmode]
Arguments:
astadr
VMS usage: ast_procedure
type: procedure entry mask
access: call without stack unwinding
mechanism: by
reference
Power recovery AST routine to receive control when a power recovery
is detected. The astadr is the address of the entry mask of this
routine.
acmode
VMS usage: access_mode
type: longword (unsigned)
access: read only
mechanism: by value
Access mode at which the power recovery AST routine is to execute.
The acmode argument is a longword containing the access mode. The
$PSLDEF macro defines symbols for the four access modes.
$SETPRI
The Set Priority service changes a process's base priority. The
base priority is used to determine the order in which executable
processes are to run.
Format:
SYS$SETPRI [pidadr] ,[prcnam] ,pri ,[prvpri]
Arguments:
pidadr
VMS usage: process_id
type: longword (unsigned)
access: modify
mechanism: by reference
Process identification (PID) of the process whose priority is to be
set. The pidadr argument is the address of the PID.
prcnam
VMS usage: process_name
type: character-coded text string
access: read only
mechanism: by descriptor--fixed
length string descriptor
Process name of the process whose priority is to be changed. The
prcnam argument is the address of a character string descriptor
pointing to a 1- to 15-character process name string.
pri
VMS usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by value
New base priority to be established for the process. The pri
argument is a longword value containing the new priority.
Priorities which are not real time are in the range 0 through 15;
real-time priorities are in the range 16 through 31.
prvpri
VMS usage: longword_unsigned
type: longword (unsigned)
access: write only
mechanism: by reference
Base priority of the process before the call to $SETPRI. The prvpri
argument is the address of a longword into which $SETPRI writes the
process's previous base priority.
$SETPRN
The Set Process Name service allows a process to establish or to
change its own process name.
Format:
SYS$SETPRN [prcnam]
Argument
prcnam
VMS usage: process_name
type: character-coded text string
access: read only
mechanism: by descriptor--fixed
length string descriptor
Process name to be given to the calling process. The prcnam
argument is the address of a character string descriptor pointing to
a 1- to 15-character process name string. If prcnam is not
specified, the calling process is given no name.
$SETPRT
The Set Protection on Pages service allows a process to change the
protection on a page or range of pages.
Format:
SYS$SETPRT inadr ,[retadr] ,[acmode] ,prot ,[prvprt]
Arguments:
inadr
VMS usage: address_range
type: longword (unsigned)
access: read only
mechanism: by reference
Starting and ending virtual addresses of the range of pages whose
protection is to be changed. The inadr is the address of a
two-longword array containing, in order, the starting and the ending
process virtual addresses. Only the virtual page number portion of
each virtual address is used; the low-order 9 bits are ignored.
retadr
VMS usage: address_range
type: longword (unsigned)
access: write only
mechanism: by reference--array reference
or descriptor
Starting and ending virtual addresses of the range of pages whose
protection was actually changed by $SETPRT. The retadr is the
address of a two-longword array containing, in order, the starting
and ending process virtual addresses.
acmode
VMS usage: access_mode
type: longword (unsigned)
access: read only
mechanism: by value
Access mode associated with the call to $SETPRT. The acmode
argument is a longword containing the access mode. The $PSLDEF
macro defines symbols for the four access modes.
prot
VMS usage: page_protection
type: longword (unsigned)
access: read only
mechanism: by value
Page protection to be assigned to the specified pages. The prot
argument is a longword value containing the protection code. Only
bits 0 to 3 are used; bits 4 to 31 are ignored.
prvprt
VMS usage: page_protection
type: byte (unsigned)
access: write only
mechanism: by reference
Protection previously assigned to the last page in the range. The
prvprt argument is the address of a byte into which $SETPRT writes
the protection of this page. The prvprt argument is useful only
when protection for a single page is being changed.
$SETPRV
The Set Privileges service enables or disables specified privileges
for the calling process.
Format:
SYS$SETPRV [enbflg] ,[prvadr] ,[prmflg] ,[prvprv]
Arguments:
enbflg
VMS usage: boolean
type: byte (unsigned)
access: read only
mechanism: by value
Indicator specifying whether the specified privileges are to be
enabled or disabled. The enbflg is a byte value. A value of 1
specifies that the privileges specified in the prvadr argument are
to be enabled. A value of 0 (the default) indicates that the
privileges are to be disabled.
prvadr
VMS usage: mask_privileges
type: quadword (unsigned)
access: read only
mechanism: by reference
Privileges to be enabled or disabled for the calling process. The
prvadr argument is the address of a quadword bit vector wherein each
bit corresponds to a privilege that is to be enabled or disabled.
prmflg
VMS usage: boolean
type: byte (unsigned)
access: read only
mechanism: by value
Indicator specifying whether the privileges are to be affected
permanently or temporarily. The prmflg is a byte value. A value of
1 specifies that the privileges are to be affected permanently, that
is, until they are again changed by using $SETPRV or until the
process is deleted. A value of 0 (the default) specifies that the
privileges are to be affected temporarily, that is, until the
current image exits (at which time the process's permanently enabled
privileges will be restored).
prvprv
VMS usage: mask_privileges
type: quadword (unsigned)
access: write only
mechanism: by reference
Privileges previously possessed by the calling process. The prvprv
argument is the address of a quadword bit vector wherein each bit
corresponds to a privilege that was previously either enabled or
disabled. If prvprv is not specified or is specified as 0, the
previous privilege mask is not returned.
$SETRWM
The Set Resource Wait Mode service allows a process to specify what
action system services should take when system resources required
for their execution are unavailable.
When resource wait mode is enabled, system services will wait for
the required system resources to become available and then will
continue execution.
When resource wait mode is disabled, system services will return to
the caller when required system resources are unavailable.
The condition value returned by $SETRWM indicates whether resource
wait mode was previously enabled or previously disabled.
Format:
SYS$SETRWM [watflg]
Argument
watflg
VMS usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by value
Indicator specifying whether system services should wait for
required resources. The watflg argument is a longword value. A
value of 0 (the default) specifies that system services should wait
until resources needed for their execution become available. A
value of 1 specifies that system services should return failure
status immediately when resources needed for their execution are
unavailable.
$SETSFM
The Set System Service Failure Exception Mode service allows a
process to specify whether or not VMS should generate a software
exception when a system service returns an error or severe error
condition value to the calling process.
The $SETSFM indicates in the condition value it returns whether
system service exception mode was enabled or disabled previous to
the call (to $SETSFM).
Initially, system service failure exception mode is disabled, so the
caller should explicitly test for successful completion following a
system service call.
Format:
SYS$SETSFM [enbflg]
Argument
enbflg
VMS usage: boolean
type: byte (unsigned)
access: read only
mechanism: by value
Number specifying whether the system service failure exception mode
is to be enabled. The enbflg argument is a byte value. A value of
1 specifies that the system service failure exception mode is
enabled. A value of 0 (the default) specifies that the system
service failure exception mode is disabled.
$SETSSF
The Set System Services Filter service inhibits user-mode calls to
certain system services. The following system services cannot be
inhibited by $SETSSF:
$ASCTIM $BINTIM $EXIT $FAO
$FAOL $PUTMSG $UNWIND
Format:
SYS$SETSSF [mask]
Arguments:
mask
VMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by value
Category of system services that are to be inhibited for user-mode
calls. The mask argument is a longword value of which only the
first byte is significant. The first byte is a bit vector wherein a
bit when set specifies a category of system service to be inhibited.
Only bits 0 and 1 are used; bits 2 to 7 are reserved.
$SETSTK
The Set Stack Limits ($SETSTK) service allows a process to change
the size of its supervisor, executive, and kernel stacks by altering
the values in the stack limit and base arrays held in P1
(per-process) space.
Format:
SYS$SETSTK inadr ,[retadr] ,[acmode]
Arguments:
inadr
VMS usage: address_range
type: longword (unsigned)
access: read only
mechanism: by reference
Range of addresses that express the stack's new limits. The inadr
argument is the address of a two-longword array containing, in
order, the address of the top of the stack and the address of the
base of the stack. Since stacks in P1 space expand from high to low
addresses, the address of the base of the stack must be greater than
the address of the top of the stack.
retadr
VMS usage: address_range
type: longword (unsigned)
access: write only
mechanism: by reference
Range of addresses that express the stack's previous limits. The
retadr argument is the address of a two-longword array into which
$SETSTK writes, in the first longword, the previous address of the
top of the stack and, in the second longword, the previous address
of the base of the stack.
acmode
VMS usage: access_mode
type: longword (unsigned)
access: read only
mechanism: by value
Access mode of the stack to be altered. The acmode argument is a
longword containing the access mode. The $PSLDEF macro defines
symbols for the four access modes. The most privileged access mode
used is the access mode of the caller.
$SETSWM
The Set Process Swap Mode service allows a process to control
whether or not it can be swapped out of the balance set.
When process swap mode is enabled, the process can be swapped out;
when disabled, the process remains in the balance set until (1)
process swap mode is re-enabled or (2) the process is deleted.
The $SETSWM service returns a condition value indicating whether
process swap mode was enabled or disabled previous to the call to
$SETSWM.
To lock some but not necessarily all process pages into the balance
set, use the Lock Pages in Memory ($LCKPAG) service.
Format:
SYS$SETSWM [swpflg]
Argument
swpflg
VMS usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by value
Indicator specifying whether or not the process can be swapped. The
swpflg is a longword value. A value of 0 (the default) enables
process swap mode, meaning the process can be swapped. A value of 1
disables process swap mode, meaning the process cannot be swapped.
$SETUAI
The Set User Authorization Information ($SETUAI) service is used to
modify the user authorization file (UAF) record for a specified
user.
Format:
SYS$SETUAI [nullarg] ,[nullarg] ,usrnam ,itmlst ,[nullarg]
,[nullarg]
Arguments:
nullarg
VMS usage: null_arg
type: longword (unsigned)
access: read only
mechanism: by value
Place-holding argument. This argument is reserved to DIGITAL.
usrnam
VMS usage: char_string
type: character-coded text string
access: read only
mechanism: by
descriptor-fixed length string descriptor
Name of the user whose user authorization file (UAF) record is
modified. The usrnam argument is the address of a descriptor
pointing to a character text string containing the user name. The
user name string may contain a maximum of 12 alphanumeric
characters.
itmlst
VMS usage: item_list_3
type: longword (unsigned)
access: read only
mechanism: by reference
Item list specifying which information from the specified user's UAF
(user authorization file) record is to be modified. The itmlst
argument is the address of a list 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.
$SNDERR
The Send Message to Error Logger service writes a user-specified
message to the system error log file, preceding it with the date and
time.
Format:
SYS$SNDERR msgbuf
Argument
msgbuf
VMS usage: char_string
type: character-coded text string
access: read only
mechanism: by
descriptor--fixed length string descriptor
Message to be written to the error log file. The msgbuf argument is
the address of a character string descriptor pointing to the message
text.
$SNDJBC
The Send to Job Controller ($SNDJBC) service creates, stops, and
manages queues and the batch and print jobs in those queues.
See the Description section for a discussion of the types of
queue supported by the VMS batch/print facility. The $SNDJBC
and $GETQUI services together provide the user interface to the VMS
Job Controller, which is the VMS queue and accounting manager.
The $SNDJBC service completes asynchronously, that is, it returns to
the caller after queueing the request, without waiting for the
operation to complete.
To synchronize the completion of most operations, use the Send to
Job Controller and Wait ($SNDJBCW) service. The $SNDJBCW service is
identical to $SNDJBC in every way except that $SNDJBCW returns to
the caller after the operation has completed.
The $SNDJBC and $SNDJBCW services supersede the Send Message to
Symbiont Manager ($SNDSMB) and Send Message to Accounting Manager
($SNDACC) services. New programs should be written using $SNDJBC or
$SNDJBCW, instead of $SNDSMB or $SNDACC, and old programs using
$SNDSMB or $SNDACC should be converted to use $SNDJBC or $SNDJBCW as
convenient.
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. 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 $SNDJBC is to perform.
The func argument is a word containing this function code. The
$SJCDEF macro defines the names of each function code.
nullarg
VMS usage: null_arg
type: longword (unsigned)
access: read only
mechanism: by value
Place-holding argument. This argument is reserved to 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 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 ($SNDJBW) and
$GETQUI services together provide the user interface to the Job
Controller (JBC) facility. The $SNDJBW service allows the user to
create, stop, and manage queues and the jobs in those queues.
Queues may be generic, batch, execution, or output queues. Jobs may
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 has completed. However,
if the requested operation is a pause queue, stop queue, or abort
job operation, $SNDJBCW returns to the caller after queueing 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 queueing 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. New programs should be written using $SNDJBC or
$SNDJBCW, instead of $SNDSMB or $SNDACC, and old programs using
$SNDSMB or $SNDACC should be converted to use $SNDJBC or $SNDJBCW as
convenient.
Format:
SYS$SNDJBCW [efn] ,func [,nullarg] [,itmlst] [,iosb] [,astadr]
[,astprm]
$SNDOPR
The $SNDOPR service performs the following functions:
o Sends a user request to operator terminals
o Sends a user cancellation-request to operator terminals
o Sends an operator reply to a user terminal
o Enables an operator terminal
o Displays the status of an operator terminal
o Initializes the operator log file
Format:
SYS$SNDOPR msgbuf ,[chan]
Arguments:
msgbuf
VMS usage: char_string
type: character-coded text string
access: read only
mechanism: by descriptor--fixed
length string descriptor
User buffer specifying the operation to be performed and information
needed to perform that operation. The msgbuf is the address of a
character string descriptor pointing to the buffer.
chan
VMS usage: channel
type: word (unsigned)
access: read only
mechanism: by value
Channel assigned to the mailbox to which the reply is to be sent.
The chan argument is a longword value containing the number of the
channel. If chan is not specified or is specified as 0 (the
default), no reply is sent.
$START_RU
Applicable only if you have the RMS Journaling option. See the VAX
RMS Journaling Manual.
The Start Recovery Unit Service denotes the beginning of a recovery
unit for use in RMS Journaling. When a recovery unit is started,
all files that have been opened by the application and marked for
recovery unit journaling (or, more specifically, all streams that
are connected to files marked for recovery unit journaling), and not
already in an active recovery unit join that new recovery unit. All
operations involving those files are part of the recovery unit until
the recovery unit is completed. If a file is involved in a recovery
unit, you cannot close the file before the recovery unit has been
completed. (More specifically, you cannot disconnect a stream
until the recovery unit has been completed.)
Format:
SYS$START_RU ru_handle
Arguments:
ru_handle
VMS Usage: ru_handle
type: longword (unsigned)
access: write only
mechanism: by reference
The ru_handle argument is the address of an unsigned longword
to which the recovery unit handle is to be returned.
$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
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 sets the event
flag to 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.
The $DDTMDEF macro defines a symbolic name for each flag bit.
$START_TRANS Operation Flags
Flag Description
DDTM$M_ Indicates that this transaction is not the
NONDEFAULT process default (current) transaction.
DDTM$M_SYNC Indicates successful synchronous completions 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.
If you specify astadr, the AST routine executes at the same access
mode as the caller of the $START_TRANS service.
Note that the completion AST will not be called if SS$_SYNCH is
returned in R0.
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).
$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 actually completed. For asynchronous
completion, you use the Start Transaction ($START_TRANS) service;
$START_TRANS starts a transaction and allocates a transaction
identifier 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.
For additional information about system service completion, refer
to the Synchronize ($SYNCH) service and to the Introduction to VMS
System Services.
Format:
SYS$START_TRANSW [efn] ,[flags] ,iosb ,[astadr] ,[astprm] ,tid
$SUSPND
The Suspend Process service allows a process to suspend itself or
another process. A suspended process cannot receive ASTs or
otherwise be executed until another process resumes or deletes it.
Format:
SYS$SUSPND [pidadr] ,[prcnam] ,[flags]
Arguments:
pidadr
VMS usage: process_id
type: longword (unsigned)
access: modify
mechanism: by reference
Process identification (PID) of the process to be suspended. The
pidadr argument is the address of the longword PID.
prcnam
VMS usage: process_name
type: character-coded text string
access: read only
mechanism: by descriptor--fixed
length string descriptor
Name of the process to be suspended. The prcnam argument is the
address of a character string descriptor pointing to a 1- to
15-character process name string.
flags
VMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by value
$SYNCH
The Synchronize service checks the completion status of a system
service that completes asynchronously.
The service whose completion status is to be checked must have been
called with the efn and iosb arguments specified because the $SYNCH
service uses the event flag and I/O status block of the service to
be checked.
Format:
SYS$SYNCH [efn] ,[iosb]
Arguments:
efn
VMS usage: ef_number
type: longword (unsigned)
access: read only
mechanism: by value
Number of the event flag specified in the call to the system service
whose completion status is to be checked by $SYNCH. The efn
argument is a longword containing this number.
iosb
VMS usage: io_status_block
type: quadword (unsigned)
access: write only
mechanism: by reference
I/O status block specified in the call to the system service whose
completion status is to be checked by $SYNCH. The iosb argument is
the address of this quadword I/O status block.
SYS$RMSRUNDWN
The RMS Rundown service closes all files opened by RMS for the image
or process and halts I/O activity. This routine performs a $CLOSE
service for each file that is opened for processing.
Format:
SYS$RMSRUNDWN buf-addr, type-value
Arguments:
buf-addr
VMS usage: char_string
type: character-coded text string
access: write only
mechanism: by
descriptor
A descriptor pointing to a 22-byte buffer that will receive the
device identification (16 bytes) and the file identification (6
bytes) of an improperly closed output file. The buf-addr argument
is the address of the descriptor that points to the buffer.
type-value
VMS usage: byte_unsigned
type: byte (unsigned)
access: read only
mechanism: by value
A single byte code that specifies the type of I/O rundown to be
performed. The type-value argument is the actual value used.
SYS$SETDDIR
The Set Default Directory service allows you to read and/or change
the default directory string for the process. You should restore
the old default directory string to its original status unless you
want the changed default directory string to last beyond the exit of
your image.
Format:
SYS$SETDDIR [new-dir-addr] [,length-addr] [,cur-dir-addr]
Arguments:
new-dir-addr
VMS usage: char_string
type: character-coded text string
access: read only
mechanism: by
descriptor-fixed length string descriptor
A descriptor of the new default directory. The new-dir-addr
argument is the address of the descriptor that points to the buffer
containing the new directory specification that RMS will use to set
the new process-default directory. If the default directory is not
to be changed, the value of the new-dir-addr argument should be 0.
length-addr
VMS usage: word_unsigned
type: word (unsigned)
access: write only
mechanism: by reference
A word that is to receive the length of the current default
directory. The length-addr argument is the address of the word that
will receive the length. Specify a value of 0 if you do not want
this value returned.
cur-dir-addr
VMS usage: char_string
type: character-coded text string
access: write only
mechanism: by
descriptor-fixed length string descriptor
A descriptor of a buffer that is to receive the current default
directory string. The cur-dir-addr argument is the address of the
descriptor that points to the buffer area that is to receive the
current directory string. Specify a value of 0 if you do not want
this to be used.
SYS$SETDFPROT
The Set Default File Protection service allows you to read and/or
write the default file protection for the process. You should
restore the old default file protection specification unless you
want the changed default to last beyond the exit of your image.
Format:
SYS$SETDFPROT [new-def-prot-addr,] [cur-def-prot-addr]
Arguments:
new-def-prot-addr
VMS usage: file_protection
type: word (unsigned)
access: read only
mechanism: by
reference
A word that specifies the new default file protection specification.
The new-def-prot-addr argument is the address of the word that
specifies the desired protection. Specify a value of 0 if you do
not want the process-default file protection to be changed.
cur-def-prot-addr
VMS usage: file_protection
type: word (unsigned)
access: write only
mechanism: by
reference
A word that is to receive the current default file protection
specification. The cur-def-prot-addr argument is the address of the
word that receives the current process-default protection. Specify
0 if this is not wanted.
$TRNLNM
The Translate Logical Name service returns information about a
logical name.
Format:
SYS$TRNLNM [attr] ,tabnam ,lognam ,[acmode] ,[itmlst]
Arguments:
attr
VMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Attributes controlling the search for the logical name. The attr
argument is the address of a longword bit mask specifying these
attributes.
tabnam
VMS usage: logical_name
type: character-coded text string
access: read only
mechanism: by descriptor--fixed
length string descriptor
Name of the table or name of a list of table names in which to
search for the logical name. The tabnam argument is the address of
a descriptor pointing to this name. This argument is required.
lognam
VMS usage: logical_name
type: character-coded text string
access: read only
mechanism: by descriptor--fixed
length string descriptor
Logical name about which information is to be returned. The lognam
argument is the address of a descriptor pointing to the logical name
string. This argument is required.
acmode
VMS usage: access_mode
type: byte (unsigned)
access: read only
mechanism: by reference
Access mode to be used in the translation. The acmode argument is
the address of a byte specifying the access mode. The $PSLDEF macro
defines symbolic names for the four access modes.
itmlst
VMS usage: item_list_3
type: longword (unsigned)
access: read only
mechanism: by reference
Item list describing the information that $TRNLNM is to return. The
itmlst argument is the address of a list of item descriptors, each
of which specifies or controls an item of information to be
returned. The list of item descriptors is terminated by a longword
of 0.
$ULKPAG
The Unlock Pages from Memory service unlocks pages that were
previously locked in memory by the Lock Pages in Memory ($LCKPAG)
service.
Locked pages are automatically unlocked and deleted at image exit.
Format:
SYS$ULKPAG inadr ,[retadr] ,[acmode]
Arguments:
inadr
VMS usage: address_range
type: longword (unsigned)
access: read only
mechanism: by reference
Starting and ending virtual addresses of the pages to be unlocked.
The inadr is the address of a two-longword array containing, in
order, the starting and the ending process virtual addresses. Only
the virtual page number portion of each virtual address is used; the
low-order 9 bits are ignored. If the starting and ending virtual
addresses are the same, a single page is unlocked.
retadr
VMS usage: address_range
type: longword (unsigned)
access: write only
mechanism: by reference--array reference
or descriptor
Starting and ending process virtual addresses of the pages actually
unlocked by $ULKPAG. The retadr is the address of a two-longword
array containing, in order, the starting and ending process virtual
addresses.
acmode
VMS usage: access_mode
type: longword (unsigned)
access: read only
mechanism: by value
Access mode on behalf of which the request is being made. The
acmode argument is a longword containing the access mode. The
$PSLDEF macro defines the symbols for the four access modes.
$ULWSET
The Unlock Pages from Working Set service unlocks pages that were
previously locked in the working set by the Lock Pages in Working
Set ($LKWSET) service. Unlocked pages become candidates for
replacement within the process's working set.
Format:
SYS$ULWSET inadr ,[retadr] ,[acmode]
Arguments:
inadr
VMS usage: address_range
type: longword (unsigned)
access: read only
mechanism: by reference--array reference or
descriptor
Starting and ending virtual addresses of the pages to be unlocked.
The inadr is the address of a two-longword array containing, in
order, the starting and the ending process virtual addresses. Only
the virtual page number portion of each virtual address is used; the
low-order 9 bits are ignored. If the starting and ending virtual
address are the same, a single page is unlocked.
retadr
VMS usage: address_range
type: longword (unsigned)
access: write only
mechanism: by reference--array reference
or descriptor
Starting and ending process virtual addresses of the pages that were
actually unlocked by $CRMPSC. The retadr is the address of a
two-longword array containing, in order, the starting and ending
process virtual addresses.
acmode
VMS usage: access_mode
type: longword (unsigned)
access: read only
mechanism: by value
Access mode on behalf of which the request is being made. The
acmode argument is a longword containing the access mode. The
$PSLDEF macro defines the symbols for the four access modes.
$UNWIND
The Unwind Call Stack service unwinds the procedure call stack; that
is, it removes a specified number of call frames from the stack.
Optionally, it may return control to a new PC after unwinding the
stack. $UNWIND is intended to be called from within a
condition-handling routine.
Format:
SYS$UNWIND [depadr] ,[newpc]
Arguments:
depadr
VMS usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
Depth to which the procedure call stack is to be unwound. The
depadr argument is the address of a longword value. The value 0
specifies the call frame of the procedure that was executing when
the condition occurred (that is, no call frames are unwound), 1
specifies the caller of that frame, 2 specifies the caller of the
caller of that frame, and so on.
newpc
VMS usage: address
type: longword (unsigned)
access: read only
mechanism: by reference
New value for the program counter (PC); this value replaces the
current value of the PC in the call frame of the procedure that
receives control when the unwinding operation is complete. The
newpc argument is a longword value containing the address at which
execution is to resume.
$UPDSEC
The Update Section File on Disk service writes all modified pages in
an active private or global section back into the section file on
disk. One or more I/O requests are queued, based on the number of
pages that have been modified.
Format:
SYS$UPDSEC inadr ,[retadr] ,[acmode] ,[updflg]
,[efn] ,[iosb] ,[astadr] ,[astprm]
Arguments:
inadr
VMS usage: address_range
type: longword (unsigned)
access: read only
mechanism: by reference--array reference or
descriptor
Starting and ending virtual addresses of the pages that are to be
written to the section file if they have been modified. The inadr
is the address of a two-longword array containing, in order, the
starting and the ending process virtual addresses. Only the virtual
page number portion of each virtual address is used; the low-order 9
bits are ignored.
retadr
VMS usage: address_range
type: longword (unsigned)
access: write only
mechanism: by reference--array reference
or descriptor
Addresses of the first and last pages that were actually queued for
writing, in the first $QIO request, back to the section file on
disk. The retadr argument is the address of a two-longword array
containing, in order, the address of the first page and the address
of the last page.
acmode
VMS usage: access_mode
type: longword (unsigned)
access: read only
mechanism: by value
Access mode on behalf of which the service is performed. The acmode
argument is a longword containing the access mode. The $PSLDEF
macro defines the symbols for the four access modes.
updflg
VMS usage: longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by value
Update specifier for read/write global sections. The updflg
argument is a longword value. The value 0 (the default) specifies
that all read/write pages in the global section are to be written to
the section file on disk, regardless of whether or not they have
been modified. The value 1 specifies that (1) the caller is the
only process actually writing the global section, and (2) only those
pages that were actually modified by the caller are to be written to
the section file on disk.
efn
VMS usage: ef_number
type: longword (unsigned)
access: read only
mechanism: by value
Event flag to be set when the section file on disk is actually
updated. The efn argument is a longword specifying the number of
the event flag.
iosb
VMS usage: io_status_block
type: quadword (unsigned)
access: write only
mechanism: by reference
I/O status block that is to receive the final completion status of
the updating 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--procedure reference or descriptor
AST routine to be executed when the section file has been updated.
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 routine. The astprm argument
is this longword parameter.
$UPDSECW
The Update Section File on Disk and Wait service writes all modified
pages in an active private or global section back into the section
file on disk. One or more I/O requests are queued, based on the
number of pages that have been modified.
The $UPDSECW service completes synchronously; that is, it returns to
the caller after writing all updated pages.
For asychronous completion, use the Update Section File on Disk
($UPDSEC) service; $UPDSEC returns to the caller after queuing the
update request, without waiting for the pages to be updated.
In all other respects, $UPDSECW is identical to $UPDSEC. Refer to
the documentation of $UPDSEC for all other information about the
$UPDSECW service.
Format:
SYS$UPDSECW inadr [,retadr] [,acmode] [,updflg] [,efn] [,iosb]
[,astadr] [,astprm]
$WAITFR
The Wait for Single Event Flag service tests a specific event flag
and returns immediately if the flag is set. Otherwise, the process
is placed in a wait state until the event flag is set.
Format:
SYS$WAITFR efn
Argument
efn
VMS usage: ef_number
type: longword (unsigned)
access: read only
mechanism: by value
Number of the event flag for which to wait. The efn argument is a
longword containing this number.
$WAKE
The Wake Process from Hibernation service activates a process that
has placed itself in a state of hibernation with the Hibernate
($HIBER) service.
Format:
SYS$WAKE [pidadr] ,[prcnam]
Arguments:
pidadr
VMS usage: process_id
type: longword (unsigned)
access: modify
mechanism: by reference
Process identification (PID) of the process to be awakened. The
pidadr argument is the address of a longword containing the PID.
prcnam
VMS usage: process_name
type: character-coded text string
access: read only
mechanism: by descriptor--fixed
length string descriptor
Process name of the process to be awakened. The prcnam argument is
the address of a character string descriptor pointing to a 1- to
15-character process name string.
$WFLAND
The Wait for Logical AND of Event Flags service allows a process to
specify a set of event flags for which it wishes to wait. The
process is put in a wait state until all specified event flags are
set, at which time $WFLAND returns to the caller and execution
resumes.
Format:
SYS$WFLAND efn ,mask
Arguments:
efn
VMS usage: ef_number
type: longword (unsigned)
access: read only
mechanism: by value
Number of any event flag within the event flag cluster that is to be
used. The efn argument is a longword containing this number.
Specifying the number of an event flag within the cluster serves to
identify the event flag cluster.
mask
VMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by value
Event flags for which the process is to wait. The mask argument is
a longword bit vector wherein a bit, when set, selects the
corresponding event flag for which to wait.
$WFLOR
The Wait for Logical OR of Event Flags service allows a process to
specify a set of event flags for which it wishes to wait. The
process is put in a wait state until any one of the specified event
flags is set, at which time $WFLOR returns to the caller and
execution resumes.
Format:
SYS$WFLOR efn ,mask
Arguments:
efn
VMS usage: ef_number
type: longword (unsigned)
access: read only
mechanism: by value
Number of any event flag within the event flag cluster that is to be
used. The efn argument is a longword containing this number.
Specifying the number of an event flag within the cluster serves to
identify the event flag cluster.
mask
VMS usage: mask_longword
type: longword (unsigned)
access: read only
mechanism: by value
Event flags for which the process is to wait. The mask argument is
a longword bit vector wherein a bit, when set, selects the
corresponding event flag for which to wait.
V54 NewFeatures
VMS Version 5.4 includes new and changed features affecting general user, system management and programming components.
Additional information available:
Overview of Hardware SupportOverview of VMS Version 5.4 Software Support
VMS Vector Processing SupportDECdtm ServicesDCL Commands and Lexical Functions
Text Processing: EVE EditorMessages Available from Online HelpVMS DECwindows User Information
System Management FeaturesProgramming Features
Overview of Hardware Support
Following are brief descriptions of the new and enhanced
hardware components supported by the VMS Version 5.4 operating
system. These include the VAX 9000, VAX 6000-400, and VAXft 3000
series computers and the new DEMNA Ethernet/802 controller.
VAX 9000 Series Computer
The VAX 9000 series computers are new, multiuser mainframe systems
that are fully compatible with other VAX computer software,
including VMS software, optional software, and applications
software. These high-performance computers utilize vector
processing and can be used as symmetric multiprocessors.
VAX 6000-400 Series Computer
The VMS Version 5.4 operating system supports the vector
processing option available on existing VAX 6000-400 series
computers.
VAXft 3000 Computer
The VAXft 3000 computer is a new fault-tolerant system that uses
VAXft System Services. Your primary sources of information are the
VAXft System Services documentation and the VAXft System Services
Software Product Description. However, there is pertinent
information in the following areas as well:
o SYSGEN
o Network Program Control (NCP)
o Error Log Utility
o VMS Version 5.4 Release Notes (Notes specific to VAXft 3000
systems)
DEMNA Ethernet/802 Controller
The VMS Version 5.4 operating system supports the DEMNA (DEC
LANcontroller 400), which is a new Ethernet/802 controller
that connects to the XMI bus.
Overview of VMS Version 5.4 Software Support
Summary of VMS Version 5.4 Software Features
VMS Version 5.4 System-Wide Features
Vector processing System-wide support for vector
processing on VAX 9000 series and
VAX 6000-400 series computers includes
the VAX Vector Instruction Emulation
Facility (VVIEF), specific DCL
commands and lexical functions,
and the Accounting, Error Log,
Monitor, SDA, Debugger, Patch, and
RTL MTH$ facilities.
DECdtm services System-wide support for DECdtm
services includes the new Log Manager
Control Program Utility (LMCP), new
MONITOR TRANSACTION command, new
and modified system services, new
TRANSACTION_ID data type, and enhanced
VAX RMS Journaling support.
VMS Version 5.4 General User Features
DCL commands New and enhanced DCL commands let
you control date compaction on the
TA90E tape drive, convert procedures
written in PostScript to callable
routines, compile fonts for the
DECwindows server, use new keywords
and qualifiers with SET ACL and
SHOW ACL, use expanded SET HOST/DTE
functions and subcommands, use symbol
scoping, set characteristics for the
VT400 family of terminals, and control
and monitor specific processors and
VAXft 3000 systems.
DCL lexical functions New and enhanced functions
return information about cluster
identification numbers, device names,
account status, verb scoping state,
volume shadowing status, vector
processing, active and recognized
CPUs in an SMP system, and symbol
creation (by other lexical functions).
EVE text editor Enhancements include box editing,
replacement of tab characters
with spaces, and new qualifiers
that let you edit large files and
specify either the character-cell or
DECwindows interface.
System Messages New or modified messages are now
available within specific VMS
facilities and online Help.
DECwindows User You can now set another session
language or change the target
screen on the Session Manager, view
PostScript files with the CDA Viewer,
change to hexadecimal or octal mode in
Calculator, use new File, Customize,
and Help menus for interacting with
Clock, and use DECwindows Mail to
display PostScript files.
VMS Version 5.4 System Management Features
AUTOGEN This command procedure now includes
support for parameter name validation,
SYS$SYSTEM:AGEN$PARAMS.REPORT
(a new file that replaces
AGEN$FEEDBACK.REPORT), reading
external parameter files, controlling
the size of page and swap files,
new feedback parameters, new defined
process logical names, a new technique
for running AUTOGEN in batch mode,
and the ability to use MAIL to send
AGEN$PARAMS.REPORT.
UETP UETP enhancements include loading and
testing of all installed and enabled
vector processors, testing of the VAX
Vector Instruction Emulation Facility
(VVIEF), and support for the RRD40
compact disc drive, including SCSI
disk configurations.
SYSMAN Enhancements to the SYSMAN Utility let
you run a SYSMAN command procedure,
define keys, spawn a subprocess, use
DCL verification, and use loadable
image commands.
VAXcluster software Enhancements include CI architecture
extensions that allow multiple CI
interfaces per CPU and multiple star
couplers per VAXcluster system; MSCP
server load sharing; and preferred
path support for DSA disks (including
RA series disks and disks accessed
through the MSCP server).
SYSGEN Enhancements include support for
MicroVAX and VAXstation configurations
that include third-party Small
Computer System Interface (SCSI)
devices and support for new SHOW
commands that display information
such as bus identification statistics,
device addresses mapped in the I/O
space for the VAXBI bus, and device
addresses mapped in the I/O space for
the XMI bus.
Error Log Utility Enhancements include support for
VAXft 3000 device types, new device
class and entry type keywords (to
support vector processing and VAX
9000 systems) used with the /EXCLUDE
and /INCLUDE qualifiers, and support
for the new /NODE qualifier, which
lets you produce a report of error
log entries for specific nodes in a
VAXcluster.
System Security System security enhancements enable
you to implement a site-defined
password policy by screening new
passwords and specifying password
algorithms.
LMCP Utility The new Log Manager Control Program
Utility (LMCP) lets the system
manager create and manage transaction
log files in a DECdtm services
environment.
Monitor Utility Enhancements include support for
vector processing, with the new
MONITOR VECTOR command and VECTOR
class, and support for DECdtm
services, with new MONITOR TRANSACTION
command and TRANSACTION class.
NCP The Network Control Program utility
now includes support for a new line
and circuit name specific to the VAXft
3000 system.
VMS Volume Shadowing VMS Volume Shadowing phase II includes
support for distributed, clusterwide
shadowing of all MSCP-compliant DSA
disks (with the same number of logical
blocks) and shadowing of all DSA
devices.
VMS Version 5.4 Programming Features
VMS Debugger Enhancements to the debugger's command
and DECwindows interfaces let you
debug programs containing VAX vector
instructions.
Linker Utility A new command line qualifier, /BPAGE,
lets you specify larger page sizes.
Mail Utility routines New callable mail routines let you
create applications that can perform
a variety of Mail Utility functions
and that can communicate with users on
remote nodes connected to the system
with DECnet-VAX.
System Services New and enhanced system services
support DECdtm services, system
security enhancements, vector
processing, volume shadowing, and
modifications to the procedure for
creating site-specific loadable
images.
Run-Time Library New parallel processing (PPL$)
routines let you inform the PPL$
facility when a new caller is forming
or joining a parallel application,
implement work queues, delete a PPL$
application or object, set and adjust
a semaphore maximum, disable event
notification, or read a spin lock
state.
New and enhanced mathematics routines
(MTH$) let you manipulate and perform
operations on vectors.
RMS Enhancements provide asynchronous
support for process-permanent files,
an increase in the local buffer
maximum, access-mode protection
for RMS services and for specific
data structures and their associated
I/O buffers, and the ability for all
applications to selectively suppress
updates to the Expiration Date and
Time, using XAB$_NORECORD XABITM.
I/O Drivers Enhancements include support for the
Pseudoterminal driver (FTDRIVER) and
Shadow Set Virtual Driver (SHDRIVER),
modifications to to the itemlist
read function of the I/O status block
(IOSB) and to the itemlist terminal
driver read verify operations for
the TRIM$_MODIFIERS item code, and
the addition of three new ACP-QIO
functions.
System Dump Analyzer New qualifiers to the SHOW PROCESS
command let you display statistics
about an image (/IMAGE) or about
the values of the registers from
the process's vector context area
(/VECTOR_REGISTERS).
Device Support Enhanced support includes VAX 9000 and
VAX 6000 series systems. Programmers
can write and debug driver software
for non-Digital-supplied devices
attached to a VAX 9000 system.
VAXTPU Enhancements include work file
support, a qualifier you can use
to specify either character-cell or
DECwindows interface, and new built-
in procedures, including GET_INFO,
that concern journal recovery, pop-up
menus, column context values for a
buffer, markers within a buffer, and
scrolling.
RMS Journaling Enhancements to VAX RMS Journaling
support DECdtm services, as well as
existing applications. Enhancements
affect the Recovery Unit Facility
(RUF), network support of remote
files, RMS record streams, the RMS
Detached Recovery server, placement of
recovery unit journals, and access of
files in a mixed-version cluster.
VMSINSTAL A new date-file parameter (P4) in
the Software Product Kit Building
Procedure (SPKITBLD.COM) lets you
specify the name of a data file. New
callbacks affect messages displayed,
and booting procedures required,
during product installations, and
how you obtain a system-generated or
installer-specified password.
DECwindows Programming Enhancements include new programming
examples in the DECW$EXAMPLES
directory, new support for the XUI
Toolkit color mixing widget (both
the Hue Lightness Saturation and
Red, Green, Blue color models),
support for the Display PostScript
system (which provides text and image
display capability for bitmapped
workstations), and CDA Viewer support
for PostScript files, Adobe Font
metrics, and DECmath fonts.
VMS Vector Processing Support
The VMS Version 5.4 operating system supports vector processing on VAX 9000 series and VAX 6000-400 series computers. The following sources also describe related aspects of VMS Version 5.4 vector processing support: UETP support DCL Debug System_Services RTL Overview of Vector Processing A single data item, having one value, is known as a scalar. A group of related scalar values, or elements, all of the same data type, is known as a vector. Traditional, scalar computers operate only on scalar values, and must process vector elements sequentially. Vector computers, on the other hand, recognize vectors as native data structures and can operate on an entire vector with a single vector instruction. A vector processor can routinely process a vector four to five times faster than a traditional computer can using only scalar instructions.
Additional information available:
VAX Vector Processing SystemsVectorized ProgramsVMS Support for Vector Processing
Managing the Vector Processing EnvironmentProgramming in a Vector Processing Environment
VAX Vector Processing Systems
An extension to the VAX architecture defines an optional design for integrated vector processing that has been adopted by several VAX processing systems. The VAX vector architecture includes 16 64-bit vector registers (V0 through V15), each containing 64 elements; vector control registers, including the vector count register (VCR), vector length register (VLR), and vector mask register (VMR); vector functional units; and a set of vector instructions. VAX vector instructions transfer data between the vector registers and memory, perform integer and floating- point arithmetic, and execute processor control functions. A more detailed description of the VAX vector architecture, vector registers, and vector instructions appears in the VAX MACRO and Instruction Set Reference Manual. Those VAX systems that comply with the VAX vector architecture are known as vector-capable systems.
Vectorized Programs
There are several methods by which you can produce a vectorized program in a VMS system. Most applications that benefit from vector processing can be developed as scalar programs in a high-level language and then submitted to a vectorizing compiler for that language. Additionally, applications may be vectorized by a call to the vectorized routines in the VMS Run-Time Library mathematics facility (RTL MTH$) or to the vectorized routines within the optional DIGITAL Extended Math Library (DXML). Finally, those programs that require strict control over the VAX vector hardware can be written in VAX MACRO and use the VAX vector instructions directly.
VMS Support for Vector Processing
The VMS operating system provides fully-shared, multiprogramming support for VAX vector processing systems. By default, VMS loads vector processing support code when initializing a VAX system that includes vector-present processors, but does not load it when initializing vector-absent systems. The VMS operating system makes the services of the vector processor available to system users by means of a software abstract known as a capability. A process requiring the vector capability and having a vector context is known as a vector consumer. VMS must schedule a vector consumer on a vector-present processor. As long as it remains a vector consumer, a process is effectively prohibited from executing on any scalar processor in the system. The VAX Vector Instruction Emulation Facility (VVIEF) is a standard feature of the VMS operating system that allows vectorized applications to be written and debugged in a VAX system in which vector processors are not available.
Managing the Vector Processing Environment
The tasks of managing a VAX vector processing system comprise the
following:
o Loading the VMS vector processing support code
o Configuring a vector processing system, using START/CPU
and STOP/CPU
o Managing processes requiring the system's vector processing
resources, using enhanced SYSGEN parameters, the Authorize
Utility, and ACLs
o Obtaining information about the status and use of the system's
vector processing resources, using DCL lexical functions
F$GETJPI and F$GETSYI, DCL commands SHOW CPU, SHOW PROCESS,
and LOGOUT/FULL, and the ACCOUNTING and MONITOR utilities.
o Loading the VAX vector emulation facility (VVIEF) bootstrap
code
These are the new system messages that may result from vector
activity in a VAX vector processing system:
ACCVIO BADCONTEXT CPUNOTACT EXQUOTA ILLVECOP
IMGVEXC INSFMEM INSFWSL NOPRIV NOSAVPEXC
VARITH VASFUL VECALIGN VECDIS
Programming in a Vector Processing Environment
Most applications that benefit from vector processing can be
developed as scalar programs in a high-level language and then
submitted to a vectorizing compiler for that language.
Additionally, applications may be vectorized by a call to the
vectorized routines in the VMS Run-Time Library mathematics
facility (RTL MTH$) or to the vectorized routines within the
optional DIGITAL Extended Math Library (DXML):
o The vectorized RTL MTH$ routines that may be called by a high-
level language application include the Level 1 Basic Linear
Algebra Subroutines (BLAS) and First-Order Linear Recurrence
(FOLR) routines. In addition, VAX vectorizing compilers (and
programs written in VAX MACRO) can generate calls to vectorized
versions of the standard scalar RTL MTH$ routines. (The
vectorized RTL MTH$ routines are fully discussed in the VMS
RTL Mathematics (MTH$) Manual.)
o The DIGITAL Extended Math Library (DXML) is an optional
software product that provides additional vectorized
mathematics routines such as BLAS Level 1-extended, 2, and
3, plus signal processing routines.
Finally, those programs that require strict control over the VAX
vector hardware can be written in VAX MACRO and use the VAX vector
instructions directly.
When programmming within a vector processing environment, you use
vector routines in the MTH$ Run-Time Library to manipulate vectors
and perform operations on vectors:
o Obtain information about a vector processing system
o Release the vector processor
o Preserve and restore a routine's vector state
o Issue vector instructions at high IPLs
o Debug a vector application
o Service vector processing exceptions
o Utilize vector information contained within the informational
packets generated by the VMS Accounting Utility and VMS Monitor
Utility
DECdtm Services
The VMS Version 5.4 operating system includes DECdtm services, which demarcate and coordinate distributed transactions. By use of the two-phase commit protocal, these services ensure consistent execution of distributed applications on the VMS operating system. In turn, these system services make use of underlying logging and communication primitives necessary to enable distributed transaction commitment. The following sources also describe related aspects of VMS Version 5.4 support for DECdtm services: o Log Manager Control Program Utility (LMCP) o MONITOR TRANSACTION Command o New and modified system services o RMS Journaling support o VMS Version 5.4 Release Notes
Additional information available:
Transaction Processing System ModelOverview of Two-Phase Commit Protocol
Managing DECdtm Services Using VMS UtilitiesProgramming Note
Transaction Processing System Model
In Digital's model for transaction processing, several components work together to execute atomic transactions. At the end-user level, user-written application programs define the task to be accomplished, such as query, update, and debit/credit. Application programs also specify how transactions are to be executed. The application programs initiate transaction execution using calls to VMS system services. At the system level, the execution of the transaction depends on the interaction of the three main transaction processing components: o Resource managers o Transaction managers o Log managers
Overview of Two-Phase Commit Protocol
Specific transaction management system services called from application programs mark the start and end of a transaction. The DECdtm system services include: o Start Transaction ($START_TRANS) o Start Transaction and Wait ($START_TRANSW) o End Transaction ($END_TRANS) o End Transaction and Wait ($END_TRANSW) o Abort Transaction ($ABORT_TRANS) o Abort Transaction and Wait ($ABORT_TRANSW) The transaction manager component of the DECdtm services coordinates the execution of these system services.
Managing DECdtm Services Using VMS Utilities
The VMS operating system provides the following utilities to
manage the information provided by the DECdtm services:
o The Log Manager Control Program Utility (LMCP) is used to
create and manage log files that are used by transaction
managers. See documentation on the VMS Log Manager Control
Program Utility for a complete description.
o The VMS Monitor Utility can be used to monitor the status of
transactions executing on the system. See documentation on the
Monitor Utility for more information.
Programming Note
To support DECdtm programming routines, there is a new VMS data type or structure for low- and high-level languages. The transaction_id data type is an octaword that stores a unique transaction identifier.
DCL Commands and Lexical Functions
VMS Version 5.4 includes new and enhanced DCL commands and lexical functions.
Additional information available:
Summary of New and Enhanced DCL CommandsSummary of New and Enhanced Lexical Functions
Summary of New and Enhanced DCL Commands
Command Enhancements
BACKUP Now includes new /MEDIA_FORMAT qualifier,
which controls data compaction on a TA90E
tape drive.
FONT New command that compiles fonts for use by
the DECwindows server and converts an ASCII
bitmap distribution format (BDF) into binary
server naturalform (SNF).
INITIALIZE Now includes new /MEDIA_FORMAT qualifier,
which controls data compaction on a TA90E
tape drive.
MOUNT Now includes new /MEDIA_FORMAT qualifier,
which controls data compaction on a TA90E
tape drive.
PSWRAP New command that invokes the PSWRAP
translator, which converts procedures
written in PostScript to callable routines.
SET ACL Now includes the new CAPABILITY keyword for
the /OBJECT_TYPE qualifier, which enables
you to specify a system capability such as
the ability to process vector instructions.
Also includes the following new qualifiers:
/BACKUP Modifies the time value
from /SINCE or /BEFORE to
select files according to
their most recent BACKUP
/EXPIRED Modifies the time value
from /SINCE or /BEFORE to
select files according to
their expiration date
/MODIFIED Modifies the time value
from /SINCE or /BEFORE to
select files according to
their last modification
date
SET HOST/DTE Now includes new qualifiers and subcommands
that provide a greater ability to control
and customize the SET HOST/DTE operation.
Specific enhancements include the following:
o Using DTEPAD, you can now control
and customize the configuration of a
connection to a remote system through a
terminal line.
o New qualifiers enable you to select all
configurational characteristics, such as
XON/XOFF flow control, the maximum number
of buffers, read, delay, and parity.
o A new interactive command mode enables
you to configure the SET HOST/DTE session
while the session is in progress.
o The following new subcommands help you
effectively control the SET HOST/DTE
operation:
CLEAR-Disconnects your local system
from DTEPAD
EXIT-Returns the session to DCL
emulation mode
QUIT-Disconnects your local system
from DTEPAD
SAVE-Saves the current configuration
settings
SEND BREAK-Sends a break to the remote
system
SET DTE-Modifies characteristics of
DTEPAD
SHOW DTE-Displays the configurable
characteristics of DTEPAD
SPAWN-Creates a subprocess of your
local process
See the VMS DCL Dictionary for complete
information about the SET HOST/DTE command.
SET MAGTAPE Now includes new /MEDIA_FORMAT qualifier,
which controls data compaction on a TA90E
tape drive.
SET SYMBOL Now includes the following new qualifiers to
control symbol scoping: /ALL, /GENERAL, and
/VERB.
SET TERMINAL Now includes a new value for the /DEC_CRT
qualifier that sets characteristics for the
VT400 family of terminals.
SHOW ACL Now includes the new CAPABILITY keyword for
the /OBJECT_TYPE qualifier, which enables
you to display a system capability such as
the ability to process vector instructions.
SHOW CPU New command that displays the current state
of the processors in a VMS multiprocessing
system.
SHOW ZONE New command that displays the current state
of a VAXft 3000 system.
START/CPU New command that starts a secondary
processor in a VMS multiprocessing system.
START/ZONE New command that adds a zone to a running
VAXft 3000 system.
STOP/CPU New command that stops a secondary processor
in a VMS multiprocessing system.
STOP/ZONE New command that removes a zone from a
running VAXft 3000 system.
VIEW Now accepts new PS input format, which
enables you to use the CDA Viewer to
view PostScript files (which use the
file extension .PS).
Summary of New and Enhanced Lexical Functions
Lexical Function Enhancements
F$CSID New function that returns the cluster
identification numbers for nodes in a
cluster.
F$DEVICE New function that returns the device names
of devices on the system.
F$ENVIRONMENT Now includes the following new item codes:
DISIMAGE Reports whether you are
logged into an account that
allows the RUN, MCR, or
foreign commands.
RESTRICTED Reports whether you are
logged into a restricted
account.
VERB_SCOPE Reports the current verb
scoping state.
F$GETDVI Now includes the following new item codes:
Volume Provide the volume-
shadowing item shadowing status of a
codes device.
TT_DECCRT4 Reports whether a terminal
is a Digital CRT4 terminal.
F$GETJPI Includes the following new item codes:
Vector item Provide information on the
codes process's use of vector
processing.
Process rights Provide information about
item codes the process's rights.
F$GETSYI Now includes the new parameter cluster-id,
which specifies the cluster node for which
information is to be returned.
Also includes the following new item codes:
ACTIVECPU_CNT Returns the number of CPUs
active in an SMP system.
AVAILCPU_CNT Returns the number of
CPUs recognized by an SMP
system.
SYSTEM_RIGHTS Contents of the system
rights list.
Vector item New item codes provide
codes information about the
vector processors in the
system.
F$TYPE Now includes the following new return
values:
PROCESS_CONTEXT Indicates whether a
symbol was created
by the F$PID lexical
function.
CLUSTER_SYSTEM_CONTEXT Indicates whether a
symbol was created
by the F$CSID
lexical function.
Text Processing: EVE Editor
The following EVE Version 2.6 new features are included in the Version 5.4 release of the VMS operating system. See the revised version of the VMS EVE Reference Manual for more detailed information. Box Editing You can edit text using rectangular areas, or boxes, as well as standard, linear ranges. For example, you can select a box containing a list or columns in a table, and then cut and paste or perform some other editing operation on the box. CONVERT TABS Command This command replaces tab characters with the appropriate number of spaces. This is useful if your file will be printed or displayed on devices with tab stops different from your settings in EVE. /WORK_qualifier This qualifier determines the work file that is used to swap memory, allowing you to edit edit very large files. /INTERFACE_qualifier This qualifer, which you use to specify either the character-cell or DECwindows interface, has been added for compatibility with other DECwindows applications. It is virtually the same as the /DISPLAY qualifier. Additional Sources of New EVE Information In addition to reading the revised VMS EVE Reference Manual to learn more about the new and changed features, you should also read the section about EDIT/TPU in the VMS DCL Dictionary (particularly the descriptions of the /JOURNAL and /RECOVER qualifiers) and review the following online help topics within EVE: Attributes Names For Keys Defaults New Features Journal Files Pending Delete List Of Topics Ranges And Boxes
Messages Available from Online Help
For the VMS Version 5.4 operating system, a system manager can
install an online Help version of the VMS System Messages and
Recovery Procedures Reference Manual. Because this is a large file,
it is not included as part of the default root Help library.
If this Help library is made available on your system, you can
access information about each message from the DCL prompt ($).
For example, you may be able to enter a command as follows:
$ HELP ERRORS DISMAL
Errors
DISMAL
all of the volumes have been dismounted
Facility: MOUNT, Mount Utility
Explanation: All of the volumes mounted by this invocation of
$MOUNT or the MOUNT command have been dismounted because of
errors that were detected after the volumes had been mounted.
Messages explaining the nature of the error that forced the
dismount usually precede this message.
User Action: Take the corrective measures mandated by the
error messages preceding DISMAL, and reenter the MOUNT
request.
Topic?
See your system manager for details about availability and use of
this library on your system.
VMS DECwindows User Information
VMS DECwindows provides the following new features: o Setting another session language o Changing the target screen o Postscript Support for the DECwindows CDA Viewer o Improvements to the DECwindows Calculator, Clock and Mail
Additional information available:
Setting Another Session LanguageChanging Your Target ScreenCDA Viewer: PostScript Support
DECwindows Calculator, Clock and Mail
Setting Another Session Language
The following languages have been added to the Customize Language dialog box in the Session Manager: o Australian o Austrian o Belgian Dutch o Belgian French o Danish o Fiji o Finnish o Hebrew o New Zealand o Papua New Guinea o Portuguese For more information about setting another session language, see the VMS DECwindows User's Guide, Version 5.3.
Changing Your Target Screen
When you run an application or choose Print Screen on a workstation that supports more than one screen display, by default DECwindows displays a dialog box asking you which screen you want to use. If you want to use the same screen every time you run an application or use PrintScreen, you can disable the screen number prompt and choose your target screen. To disable the screen number prompt or change your target screen, choose Screen Number... from the Session Manager's Customize menu. The Session Manager displays the Customize Screen Number dialog box. By clicking on the Prompt for Screen buttons, you will not be asked which screen you want to use. When you choose your target screen in the Customize Screen Number dialog box, DECwindows will run applications (or PrintScreen) on the screen you designated.
CDA Viewer: PostScript Support
The DECwindows CDA Viewer now supports viewing of PostScript
files. To view a PostScript file, select the CDA Viewer menu item
from the FileView Applications menu. In the Open window, click on
PS in the File Format box and then select the PostScript file you
want to view.
From DCL, you can also enter the VIEW command to open a PostScript
document for viewing:
$ VIEW filename.PS /FORMAT=PS /INTERFACE=DECWINDOWS
When invoking the CDA Viewer from the DCL prompt, PostScript files
do not require processing options.
New Processing Options for Viewing PostScript Files
In addition to the Default Paper Size option, new processing
options specific to viewing PostScript files are available in the
Paper Size dialog box:
o Orientation radio box
The Orientation radio box lets you select the orientation
for displaying PostScript files. By default, the CDA Viewer
displays files in the same portrait or landscape mode in
which they were created. You can use the Orientation radio
box to select different orientations to view files in reverse
landscape mode or upside down.
o Scale Factor
The Scale Factor lets you scale the page display size of your
PostScript file. The number you select indicates whether the
CDA Viewer will shrink or enlarge the page display.
o Use Comments toggle button
The Use Comments option indicates that the CDA Viewer should
interpret comments such as the location of page breaks in a
PostScript file.
o Use Bitmap Widths toggle button
The Use Bitmap Widths option adjusts the display of your
PostScript file for improved viewing on the screen. Specify the
Use Bitmap Widths option so that the CDA Viewer will use
spacing formulas designed for bitmaps (screen images) instead
of those designed for print.
o Use Fake Trays toggle button
The Use Fake Trays option allows you to view a PostScript file
that contains tray size directives. Tray size directives are
instructions that tell the printer what tray size to use.
o Watch Progress toggle button
The Watch Progress option allows you to view a PostScript
file while it is being processed for display in the CDA
Viewer window. You can view a page as it is being processed,
rather than waiting to view the entire page after it has been
processed.
DECwindows Calculator, Clock and Mail
Calculator Calculator now has two additional modes: hexadecimal and octal. When you first start the Calculator, it is in decimal mode. A new Mode menu contains Hexadecimal and Octal menu entries for changing modes. The keyboard display and functions change according to the mode. Clock Clock now has a menu bar with File, Customize, and Help menus for interacting with Clock. The menu bar provides an alternative to the previous method of pressing MB2 while pointing to the Clock display. The only menu item under File is Quit. Choose Quit to exit from Clock. The Customize menu enables you to change the Clock display. The Customize Menu has three menu items. The menu items correspond to the Settings..., Save Settings, and Use System Settings previously available on a pop-up menu. Choosing the Settings... menu item displays the Clock Settings dialog box. The only change to the dialog box is the addition of a toggle button for Menu Bar. By default, the Menu Bar button is shaded and the menu bar is displayed. If you do not want the menu bar displayed, click on the Menu Bar button. Help is now available directly as a menu on the menu bar, rather than from a pop-up dialog box. Mail Mail can now display PostScript files, provided the files you send or receive contain only PostScript language. A PostScript file always begins with a percent sign and an exclamation point (%!). If any other text precedes the %!, Mail cannot display the file. For example, when mail is forwarded, additional text (in the form of extra mail headers) is often inserted at the beginning of the file. Because this additional text precedes the %!, Mail cannot display the PostScript file correctly. To avoid this problem, use an editor to remove all headers before you forward a mail message in PostScript format. Similarly, if you receive a PostScript file that does not display properly, use an editor to remove all headers (or any other text that precedes the %!), and forward the file to yourself. The file should then display properly.
System Management Features
VMS Version 5.4 provides new system management features.
Additional information available:
AUTOGEN Command ProcedureUser Environment Test Package (UETP): Vector Support
System Generation Utility (SYSGEN)SYSMAN UtilityVAXcluster Management
Error Log UtilitySecurityMonitor UtilityVMS Log Manager Control Program Utility
Network Control Program (NCP)VMS Volume Shadowing Phase II
AUTOGEN Command Procedure
The following changes to the AUTOGEN command procedure are new
for VMS Version 5.4
Parameter Name Validation
When AUTOGEN reads a parameter file such as MODPARAMS.DAT, it now
checks to determine if the parameter names specified in the file
are valid.
AGEN$FEEDBACK.REPORT Replaced by New File
The file SYS$SYSTEM:AGEN$FEEDBACK.REPORT has been replaced by a
new file called SYS$SYSTEM:AGEN$PARAMS.REPORT. This new file
contains all of the information previously contained in
AGEN$FEEDBACK.REPORT, as well as information about the non-
feedback parameters and additional messages.
MODPARAMS.DAT Includes External Parameter Files
To aid in cluster management, AUTOGEN can now read external
parameter files specified within MODPARAMS.DAT. This feature
allows system managers to maintain both cluster-wide and system-
specific versions of AUTOGEN parameters.
MIN_, MAX_, and ADD_ Values Allowed for Page and Swap Files
You can now control the size of page and swap files by specifying
MIN_, MAX_, and ADD_ values in a parameter file. The syntax for
specifying MIN_, MAX_, and ADD_ values is identical to that used
with other parameters.
For example, you can control the size of general page and swap
files by including one or more of the following lines in a
parameter file:
PAGEFILE = 20000
ADD_PAGEFILE = 5000
MIN_SWAPFILE = 1500
MAX_SWAPFILE = 4000
New Feedback Parameters
The existing parameters LRPCOUNT and LMNSHASHTBL are now feedback
parameters. This means that AUTOGEN can set these parameters
using data collected in AUTOGEN feedback mode.
Logical Names Defined by AUTOGEN
To aid in system management, AUTOGEN defines three process logical
names to indicate how AUTOGEN was last run. These logical names
are assigned a character string value each time AUTOGEN is run
on a system. The following table lists and describes the logical
names:
Logical
Name Description
AGEN$P1 The starting phase of AUTOGEN, for example, SAVPARAMS
AGEN$P2 The end phase of AUTOGEN, for example, TESTFILES.
If an error occurred which caused AUTOGEN to abort,
then "_E" is appended to the phase name, for example,
GENPARAMS_E.
AGEN$P3 The mode of execution, that is, either FEEDBACK or
NOFEEDBACK.
New Technique for Running AUTOGEN in Batch Mode
As of VMS Version 5.2-1, Digital recommends a new technique for
running AUTOGEN. This technique automates AUTOGEN feedback,
allowing the system manager to receive reports from multiple
systems on a regular basis. To use this technique, create a batch-
oriented procedure which runs AUTOGEN in two stages.
The first stage of the command procedure runs AUTOGEN at peak
times to collect data on realistic system loads. The following
command accomplishes this task:
@ SYS$UPDATE:AUTOGEN SAVPARAMS SAVPARAMS FEEDBACK
Executing this command does not affect the performance of the
system.
The second stage of the command procedure runs AUTOGEN again
during off-peak hours to interpret the data collected in the first
stage. The following command accomplishes this task:
@SYS$UPDATE:AUTOGEN GETDATA TESTFILES FEEDBACK
The procedure sends the resulting report, contained in the file
AGEN$PARAMS.REPORT, to the SYSTEM account using the following MAIL
command:
$ MAIL/SUBJECT="AUTOGEN FEEDBACK REPORT FOR system-name" -
SYS$SYSTEM:AGEN$PARAMS.REPORT SYSTEM
Review this report on a regular basis to see whether the load on a
system has changed. If AUTOGEN's calculations are different from
the current values, correct the tuning by executing AUTOGEN with
one of two commands:
o If the system can be shutdown and rebooted immediately, execute
the following command:
@SYS$UPDATE:AUTOGEN GETDATA REBOOT FEEDBACK
o If the system can not be shutdown and rebooted immediately,
execute the following command to reset the system parameters:
@SYS$UPDATE:AUTOGEN GETDATA SETPARAMS FEEDBACK
The new parameters will take affect the next time the system
boots.
AUTOGEN Can Send AGEN$PARAMS.REPORT Using MAIL
After closing the AGEN$PARAMS.REPORT file, AUTOGEN now checks for
the existence of a file named SYS$UPDATE:AGEN$MAIL.COM. If this
file exists it is executed from within AUTOGEN. (Note, however,
that AUTOGEN does not execute AGEN$MAIL.COM during VMS upgrades or
installations, or after minimum system boots.)
User Environment Test Package (UETP): Vector Support
With the VMS Version 5.4 release, the User Environment Test
Package (UETP) automatically loads and tests all installed and
enabled vector processors. It also provides the capability to test
the VAX Vector Instruction Emulation Facility (VVIEF).
UETP also supports supports the following:
o The RRD40 compact disc drive, including multiple RRD40 units
o SCSI disk configurations that allow both read-only compact discs
and standard read/write disks to use the same device controller
name
multiple CDROM units and enhanced support for
the RRD40 controller.
System Generation Utility (SYSGEN)
These are the enhancements to the SYSGEN utility for Version 5.4
of the VMS operating system.
SCSI NOAUTO SYSGEN Parameter
VMS Version 5.4 defines the special SYSGEN parameter SCSI_NOAUTO
to be of use to MicroVAX/VAXstation configurations that include
third-party Small Computer System Interface (SCSI) devices. (A
complete discussion of this topic appears in the VMS Version 5.3
Small Computer Systems Interface (SCSI) Device Support Manual.)
The SCSI_NOAUTO SYSGEN parameter replaces the VMSD1 SYSGEN
parameter.
New Supported Device Names for VAXft 3000 Systems
For the VMS Version 5.4 release, the System Generation Utility
(SYSGEN) supports seven new device names specific to the VAXft
3000 system:
Code Name Device Type
CM Environmental control monitor
GD DMA driver
EF Logical Ethernet driver
EP Physical Ethernet driver
PW DSSI disk driver
SF Logical DSF driver
SM Physical DSF driver
SHOW/BI=BIindex SYSGEN Command
Displays device addresses that are currently mapped in the I/O
space for the VAXBI bus. It also displays node and nexus numbers
and generic names of UNIBUS and MASSBUS adapters, VAXBI adapters,
memory controllers, and interconnection devices such as the DR32
and CI.
Use of the SHOW/BI=BIindex command requires the CMEXEC privilege.
Format
SHOW/BI=BIindex
SHOW/BUS=busId SYSGEN Command
Displays the buses and any subsequent attached buses and all
attached device node numbers, generic names of processors,
memory modules, adapters, VAXBI adapters, memory controllers,
and interconnection devices such as the NI.
Use of the SHOW/BUS command requires the CMEXEC privilege.
Format
SHOW/BUS=busId
Example
SYSGEN> SHOW/BUS
The command in this example displays information about all the
adapters on the system buses.
Cpu Type: VAX 8800 Cpu Connection: NMI
Bus Node Generic Name Nexus(hex) Connection Address
BI 00 00 CI 0000
BI 00 02 BI - NMI Adapter (NBIB) 0002
BI 0 07 BI Combo Board (DMB32) 0007
BI 01 00 UB 0010
BI 01 02 BI - NMI Adapter (NBIB) 0012
BI 01 07 BI - NI Adapter (DEBNA) 0017
SHOW/XMI=BIindex SYSGEN Command
Displays device addresses that are currently mapped in the I/O
space for the XMI bus. It also displays node and nexus numbers
and generic names of processors, adapters, VAXBI adapters, memory
controllers, and interconnection devices such as the NI.
Use of the SHOW/XMI=BIindex command requires the CMEXEC privilege.
Format
SHOW/XMI=BIindex
SYSMAN Utility
With VMS Version 5.4, the VMS System Management Utility (SYSMAN)
includes new features that make it easier for system managers to
use SYSMAN to manage nodes and clusters. The following list
provides a brief summary of the new capabilities. For complete
information, see the VMS SYSMAN Utility Manual.
o Running a SYSMAN Command Procedure
The SYSMAN command @ now executes the specified SYSMAN command
procedure on each node in the environment.
o Defining Keys with the DEFINE command
SYSMAN enables you to define keys to execute SYSMAN commands. By
defining keys, you can avoid typing lengthy SYSMAN commands. You
can also put your key definitions in a SYSMAN initialization
file, which executes each time you invoke SYSMAN.
o Spawning a Subprocess from within SYSMAN
If you are in SYSMAN but want to leave temporarily to perform
other functions (such as displaying a directory listing or
printing a file) and then return to SYSMAN, you can use the
SPAWN and ATTACH commands. These commands function in much the
same way as the DCL commands SPAWN and ATTACH.
o Using DCL Verification
Using the SYSMAN command SET PROFILE/VERIFY, you can set DCL
verification (both procedure and image) for future DO commands.
This enables you to view the lines of DCL procedures as they
execute.
o Using Loadable Image Commands
CAUTION
SYS_LOADABLE commands are not intended for general use. Only
advanced system programmers should use these commands.
The SYS_LOADABLE command set adds and removes executive loaded
images from the list of images that are loaded by the SYSINIT
process during the bootstrap. This new feature is intended
primarily for system programmers to use when writing routines
that implement site-specific policies or special algorithms.
These routines can either replace or augment the built-in VMS
policies.
VAXcluster Management
The following enhancements are now available with VMS Version
5.4 VAXcluster systems:
o CI architecture extensions
o MSCP server load sharing
o Preferred path support for DSA disks)
CI Architecture Extensions
Extensions to the CI architecture allow the application of
multiple CI interfaces per CPU and multiple star couplers per
VAXcluster system. These extensions make possible VAXcluster
systems with many times the data throughput capacity of current
VAXcluster systems with a single star coupler.
MSCP Server Load Sharing
Beginning with VMS V5.4, MSCP servers monitor their I/O traffic
and periodically calculate a Load Available rating to indicate
available capacity for I/O requests.
Load Available is calculated by counting the read and write
requests sent to the server and periodically converting this
to requests per second and substracting this calculated value
from the server's Load Capacity (also specified in requests per
second).
This information is communicated to the V5.4 MSCP class driver
(DUDRIVER and DSDRIVER). When a disk is mounted or a failover
occurs, the class driver selects the server with the highest Load
Available rating to access the disk.
Load Balancing is enabled and controlled by the SYSGEN parameters
MSCP_LOAD and MSCP_SERVE_ALL. In most cases, the values
established by CLUSTER_CONFIG.COM are appropriate.
MSCP_SERVE_ALL determines whether the server participates in load
balancing. If it is set to 2 (serve only local disks), the server
does not monitor its I/O traffic and does not participate in
load balancing. Other valid settings for MSCP_SERVE_ALL (0, 1)
result in the server monitoring I/O traffic and communicating Load
Available information to the class drivers.
MSCP_LOAD is used to communicate Load Capacity to the server, in
addition to its existing function of controlling the loading of
the MSCP server. If it is set to 1, the MSCP server is loaded and
its Load Capacity is set to a default value based upon CPU type.
If MSCP_LOAD is set to a value greater than one, the server is
loaded and its Load Capacity set to that value.
As before, setting MSCP_LOAD to zero disables loading of the MSCP
server.
Preferred Path Support for DSA disks
VMS V5.4 includes support for specifying a preferred path for DSA
disks. This includes RA series disks and disks accessed through
the MSCP server.
If a preferred path is specified for a disk, the MSCP disk class
drivers (DUDRIVER and DSDRIVER) uses the path as their first
attempt to locate the disk and bring it online as a result of
a DCL MOUNT command or failover of an already mounted disk.
In addition, it is possible to initiate failover of a mounted disk
to force the disk to the preferred path or to use load balancing
information for disks accessed via MSCP servers.
The preferred path is specified by a $QIO function IO$_SETPRFPTH,
with the P1 parameter containing the address of a counted ASCII
string (.ASCIC). This string is the node name of the HSC or VMS
system that is to be the preferred path. The node name must match
an existing node known to the local node and if it is a VMS system
it must be running the MSCP server. This function does not move
the disk to the preferred path. For more information on the IO$_
SETPRFPTH function, refer to the VMS I/O User's Reference Manual:
Part I.
Error Log Utility
For the VMS Version 5.4 operating sytem, the Error Log Utility now
supports device types used in VAXft 3000 systems, new device
keywords, and a new qualifier.
The following devices report to the Error Log Utility:
RF31, TF70, DSF32, CM, EP, EF, PW, SM, SF
New Keywords for /EXCLUDE and /INCLUDE_Qualifiers
The /EXCLUDE and /INCLUDE qualifiers accept new device class and
entry type keywords, as follows:
Device Class Keyword Function
ADAPTER Includes or excludes entries for adapter
errors
CACHE Includes or excludes entries for memory
caching errors
INFORMATIONAL Includes or excludes error log entries such
as media quality reports from magnetic tape
devices
VECTOR Includes or excludes entries for vector
processing errors
Entry Type Keyword Function
CONFIGURATION Includes or excludes entries that describe
system configuration
SYNDROME Includes or excludes VAX 9000 console-
generated entries that provide encoded
syndrome values used by Customer Services
New Qualifier: /NODE
The Error Log Utility now accepts the /NODE qualifier. This
qualifier enables you to generate a report consisting of error
log entries for specific nodes in a VAXcluster. The format (with
an example) of the /NODE qualifier is as follows:
Format
/NODE =(node-name[,...])
Parameter
node-name
Specifies the names of one or more VAXcluster members. Names
cannot exceed six characters. If more than one node name is
entered, you must specify a comma-separated list of node names
enclosed in parentheses.
Example
$ ANALYZE/ERROR_LOG/NODE=(ORANGE,NASSAU) ERRLOG.OLD;72
In this example, a VAXcluster includes members ORANGE, PUTNAM, and
NASSAU. The output consists of only those entries that were logged
for VAXcluster members ORANGE and NASSAU.
Security
In addition to the enhancements to SET ACL and SHOW ACL, and the
new and modified system services, the VMS Version 5.4 release
provides the following new security features for system managers:
Site-Defined Password Policy
Starting with VMS Version 5.4, passwords selected by users can
be screened for acceptability. The VMS system automatically
compares new passwords against a system dictionary to ensure that
a password is not a native language word. It also maintains a
history list of a user's passwords and compares each new password
against this list to guarantee that an old password is not reused.
Sites can screen passwords further by developing and installing
an image that filter passwords for words that are particularly
sensitive to the installation.
In addition, a site with contractual obligations to use special
algorithms for encrypting passwords will be able to use them.
Screening New Passwords
Sites that choose to let users select their own passwords rather
than use the password generator can now screen user-selected
passwords. As of Version 5.4, the VMS system automatically
compares new passwords against a system dictionary, which in
stored in SYS$LIBRARY, to ensure that a password is not a native
language word. The VMS system also maintains a list of all the
passwords a user has had during the year and compares each new
password against this history list to guarantee that an old
password is not reused.
Both the dictionary and the history search can be disabled through
the Authorize Utility. You disable the dictionary search with the
DISPWDDIC option to the /FLAGS qualifier; you disable the history
search with the DISPWDHIS option to the /FLAGS qualifier.
Password History List
VMS keeps a year's worth of data in the password history list. If
the password limit is exceeded, the system forces a user to accept
generated passwords. By default, the list stores 60 passwords. A
security administrator can change the defaults for the length of
time passwords are retained and the maximum number of passwords
per list.
System Logical Name Default Min Max Units
SYS$PASSWORD_HISTORY_LIFETIME 365 1 28000 days
SYS$PASSWORD_HISTORY_LIMIT 60 1 2000 absolute
count
Using the DCL command DEFINE, you can change the defaults for the
capacity and lifetime of the password history list. For example,
to increase the capacity of the history list from 60 passwords
to 100, you would add the following line to the command procedure
SYLOGICALS.COM, which is located in SYS$MANAGER.
$ DEFINE/SYSTEM/EXEC SYS$PASSWORD_HISTORY_LIMIT 100
There is a correspondence between the lifetime of a password
history list and the number of passwords allowed on the list.
For example, if you increase the password history lifetime to four
years and your passwords expire every two weeks, you would need to
increase the password history limit to at least 104 (4 years times
26 passwords a year). The password history lifetime and limit can
be changed dynamically but they should be consistent across all
nodes on the cluster.
Sites using secondary passwords might need to double the password
limit to account for the secondary password storage.
The password history list is located in SYS$SYSTEM. The list
can be redirected off the system disk using the logical name
VMS$PASSWORD_HISTORY. This logical name should also be placed
in SYS$MANAGER:SYLOGICALS.COM.
Site-Specific Filter
Security administrators can develop a site-specific password
filter to ensure that passwords are not words readily associated
with their site, for example, product names or personnel names. A
filter can also check for particular character variations.
To create a list of site-specific words, you write the source
code, create a shareable image, install the image, and, finally,
enable the policy by setting a SYSGEN parameter. Installing and
enabling a site-specific password filter requires both SYSPRV and
CMKRNL privileges. In addition, if INSTALL and SYSPRV file access
auditing are enabled, multiple security alarms are generated when
the password filter image is installed and the required change to
the SYSGEN parameter is noted on the operator console.
The shareable image contains two global routines that are
called by the VMS Set Password Utility whenever a user changes
a password.
WARNING
The two global routines allow a security administrator
to obtain both the proposed plaintext password and its
equivalent quadword hash value. All security administrators
should be aware of this feature as its subversion by a
malicious privileged user will compromise your system's
security.
Therefore, Digital recommends that you place security alarm ACEs
on the password filter image and its parent directory.
Specifying a Password Algorithm
The VMS operating system protects passwords from disclosure
through encryption. VMS algorithms transform passwords from
plain text strings into cipher text, which is then stored in
the user authorization file (UAF). Whenever a password check is
done, the check is based on the encrypted password, not the plain
text password. The system password is always encrypted with an
algorithm known to the VMS system.
The /ALGORITHM qualifier in the Authorize Utility allows you to
define which algorithm the VMS system should use to encrypt a
user's password, both primary and secondary. Your choices are the
current VMS algorithm or a site-specific algorithm. The syntax is
as follows:
/ALGORITHM=keyword=type [=value]
To assign the VMS password encryption algorithm for a user, you
would enter the following command.
UAF> MODIFY HOBBIT/ALGORITHM=PRIMARY=VMS
If a site-specific algorithm is selected, you must give a value to
identify the algorithm.
UAF> MODIFY HOBBIT/ALGORITHM=CURRENT=CUSTOMER=128
You must create a site-specific $HASH_PASSWORD in which you
define an algorithm number. This number has to correspond with the
number used in the AUTHORIZE command MODIFY/ALGORITHM.
Whenever a user is assigned a site-specific algorithm, the
Authorize Utility reports this information in the display provided
by the SHOW command.
Arguments to the /ALGORITHM qualifier
Keyword Function
BOTH Set the algorithm for primary and secondary
passwords.
CURRENT Set the algorithm for the primary, secondary, both,
or no passwords depending on account status. Current
is the default value.
PRIMARY Set the algorithm for the primary password only.
SECONDARY Set the algorithm for the secondary password only.
Type Definition
VMS The VMS operating system reserves the range 0-127
for its algorithms.
CUSTOMER A numeric value in the range 128-255 identifies a
customer algorithm.
Monitor Utility
The VMS Monitor Utility (MONITOR) is a system management tool that
you can use to obtain information on operating system performance.
This chapter describes the following enhancements to Version 5.4
of the VMS Monitor Utility:
o New MONITOR TRANSACTION command and TRANSACTION class (for use
within a DECdtm services environment)
o New MONITOR VECTOR command and VECTOR class (for use within a
vector processing environment)
Additional information available:
MONITOR TRANSACTION CommandMONITOR VECTOR Command
MONITOR TRANSACTION Command
The MONITOR TRANSACTION command initiates monitoring of the
TRANSACTION class, which shows information about transactions
coordinated by the DECdtm services. (For a complete description of
DECdtm services, see Chapter 3.)
Use this command as follows:
1. Invoke the MONITOR Utility by entering the DCL command MONITOR.
The utility then displays the following prompt:
MONITOR>
2. At the MONITOR prompt, enter the MONITOR TRANSACTION command.
Format
MONITOR TRANSACTION
The following qualifiers apply to the TRANSACTION class display:
Qualifier Action
/ALL Specifies that a table of all available statistics
(current, average, minimum, and maximum) is to be
included in the display and summary output. For summary
output, this qualifier is the default for all classes;
otherwise, it is the default for all classes except
CLUSTER, MODES, PROCESSES, STATES, and SYSTEM, and
VECTOR.
/AVERAGE Selects average statistics to be displayed in a bar
graph for display and summary output.
/CURRENT Selects current statistics to be displayed in a bar
graph for display and summary output. The /CURRENT
qualifier is the default for the CLUSTER, MODES,
STATES, and SYSTEM and VECTOR classes.
/MAXIMUM Selects maximum statistics to be displayed in a bar
graph for display and summary output.
/MINIMUM Selects minimum statistics to be displayed in a bar
graph for display and summary output.
MONITOR VECTOR Command
The MONITOR VECTOR command displays the number of 10-millisecond
clock ticks per second in which one or more vector consumers have
been scheduled on each currently-configured vector processor in
the system. Because the VMS operating system schedules vector
consumers only on those processors identified as "vector present,"
the VECTOR class output never displays vector CPU time for those
processors that are "vector absent."
Note that because vector consumers can use either or both
the vector CPU and scalar CPU components of a vector-present
processor, the vector CPU time in the VECTOR class display is not
a strict measure of the actual usage of the processor's vector CPU
component. Rather, it indicates the time during which a scheduled
vector consumer has reserved both vector CPU and scalar CPU
components of the vector-present processor for its own exclusive
use.
Use this command as follows:
1. Invoke the MONITOR Utility by entering the DCL command MONITOR.
The utility then displays the following prompt:
MONITOR>
2. At the MONITOR prompt, enter the MONITOR VECTOR command. The
format, description, and an example of this command follow.
Format
MONITOR VECTOR
The following qualifiers apply to the VECTOR class display:
Qualifier Action
/ALL Specifies that a table of all available statistics
(current, average, minimum, and maximum) is to be
included in the display and summary output. For summary
output, this qualifier is the default for all classes;
otherwise, it is the default for all classes except
CLUSTER, MODES, PROCESSES, STATES, and SYSTEM, and
VECTOR.
/AVERAGE Selects average statistics to be displayed in a bar
graph for display and summary output.
/CURRENT Selects current statistics to be displayed in a bar
graph for display and summary output. The /CURRENT
qualifier is the default for the CLUSTER, MODES,
STATES, and SYSTEM and VECTOR classes.
/MAXIMUM Selects maximum statistics to be displayed in a bar
graph for display and summary output.
/MINIMUM Selects minimum statistics to be displayed in a bar
graph for display and summary output.
VMS Log Manager Control Program Utility
The Log Manager Control Program (LMCP) is the utility used to
create and maintain transaction log files.
More on-line help is available from the Log Manager Control
Program Utility. To invoke LMCP, enter the following command
in response to the DCL prompt:
$ RUN SYS$SYSTEM:LMCP
The utility responds with the prompt:
LMCP>
After you invoke LMCP, you can enter HELP on any of the LMCP
commands.
Network Control Program (NCP)
The VMS Network Control Program (NCP) now supports a new line
and circuit name specific to the VAXft 3000 system: KFE-n, where
n is 0 or a positive number designating the device's hardware
controller.
When you enter NCP commands from a VAXft 3000 system that is
connected to your DECnet-VAX network, the KFE-n line and circuit
name is displayed, as follows:
$ RUN SYS$SYSTEM:NCP <Return>
NCP> SHOW KNOW LINE <Return>
Line Volatile Summary as of 31-AUG-1990 12:50:03
Line State
KFE-0 on
$ RUN SYS$SYSTEM:NCP <Return>
NCP> SHOW KNOW LINE <Return>
Circuit Volatile Summary as of 31-AUG-1990 12:52:03
Loopback Adjacent
Circuit State Name Routing Node
KFE-0 on 8.999 (JUPE)
VMS Volume Shadowing Phase II
Volume shadowing is the process of maintaining multiple copies
of the same data on two or more disk volumes. This duplication
of data provides greater data availability and faster data
accessibility. Volume shadowing provides high availability by
insuring against data loss resulting from media deterioration
or through controller or device failure. When data is recorded
on more than one disk volume, you have access to critical data
even when one volume is unavailable. Disk input/output operations
continue with the remaining members of the shadow set.
The system can also find data more quickly because it can search
more than one disk. Because a shadow set is made up of multiple
disks containing the same data, the shadow set can use the
additional read heads to respond to multiple read requests at the
same time. In addition, when normal media deterioration renders
sections of a volume unreadable, systems with volume shadowing
can read the duplicate data and copy it to the failing volume to
repair data.
Before Version 5.4, VMS supported only phase I volume shadowing
(refer to the VAX Volume Shadowing Manual). This type of
shadowing provides centralized shadowing using HSC controllers
with compatible DSA disks. Phase I shadowing is limited to CI
configurations on a single system or a VAXcluster.
VMS Volume Shadowing phase II supports the following:
o Clusterwide shadowing of all MSCP-compliant DSA disks having
the same physical geometry (having the same number of logical
blocks) on a single system or located anywhere in a VAXcluster
system.
Volume shadowing phase II supports clusterwide shadowing of all
DSA devices. Phase II is not limited to HSC-controlled disks
but extends volume shadowing capabilities to all DSA disks
including local adapters, all DSSI (RF series) disk devices on
any VAX computer, all interfaces (including but not limited to
the KFQSA interface), and across MSCP servers.
o Distributed, not centralized, shadowing
Volume shadowing phase II creates and maintains virtual units
in a distributed fashion on each node in the cluster. Phase
II supports shadowing on a single system or in a VAXcluster
system where interprocessor communication is carried out over a
computer interconnect (CI), Digital small systems interconnect
(DSSI), mixed-interconnect configuration, or the Ethernet.
Thus, volume shadowing provides fault tolerance resulting from
disk media errors across the full range of VAX processors and
configurations.
o Shadowing of the system disk and Files-11 On-Disk Structure
Level 2 (ODS2) data disks
o Shadowing capabilities across different controllers.
Shadow set member units can be located on different controllers
and VMS MSCP servers.
o Shadowing capabilities with mixed phases
It is possible to use both phase I and phase II shadowing on
the same node at the same time. You can also mix phase I and
phase II shadowing in a VAXcluster system.
See the new VMS Volume Shadowing Manual for complete information
about phase II volume shadowing.
Programming Features
VMS Version 5.4 provides new programming features.
Additional information available:
VMS Debugger: Vector SupportUtility Routines:MAILSystem Services
Run-Time Library RoutinesVMS Record Management ServicesVAX RMS Journaling
I O Driver SupportSystem Dump Analyzer Utility (SDA)Device Support
VAX Text Processing Utility (VAXTPU)DECwindows and CDA Programming Features
VMS Debugger: Vector Support
New features allow you to use Version 5.4 of the VMS Debugger to debug vectorized programs (programs that use VAX vector instructions).
Additional information available:
Debugging Vectorized ProgramsCommand Interface: New and Enhanced Commands and Qualifiers
DECwindows Interface: Enhancements to Menus and Dialog Boxes
Debugging Vectorized Programs
You can now perform the following debugging tasks, using either
the debugger's command or DECwindows interface:
o Display information about the availability and use of the
vector processor on your system
o Control and monitor the execution of vector instructions with
breakpoints, watchpoints, and so on
o Specify built-in symbols for the vector registers (%V0 through
%V15) and the vector control registers (%VCR, %VLR, and %VMR).
o Examine and deposit into the vector registers and the vector
control registers
o Display vector instructions using a screen-mode instruction
display
o Examine and deposit vector instructions and their operands
o Perform masked operations on vector registers to display only
certain register elements or override the masking associated
with a vector instruction
o When using the EXAMINE command, specify composite address
expressions of a complex form, such as might be appropriate for
a vectorized program. (Note that this feature is not restricted
to vectorized programs.)
o Display the decoded results of vector floating-point
exceptions.
o Control synchronization between the scalar and vector
processors
o Save and restore the current vector state when using the CALL
command to execute a routine that might affect the vector state
o Display vector register data using a screen-mode display
Command Interface: New and Enhanced Commands and Qualifiers
The following list identifies new and enhanced commands and qualifiers for the debugger's command interface: o CALL/[NO]SAVE_VECTOR_STATE o CANCEL BREAK/VECTOR_INSTRUCTION o CANCEL TRACE/VECTOR-INSTRUCTION o EXAMINE/FMASK, /TMASK, /OPERANDS o SET BREAK/VECTOR_INSTRUCTION, /INSTRUCTION[=(opcode[,...])] o SET STEP VECTOR_INSTRUCTION, INSTRUCTION[=(opcode[,...])] o SET TRACE/VECTOR_INSTRUCTION, /INSTRUCTION[=(opcode[,...])] o SET VECTOR_MODE [NO]SYNCHRONIZED o SHOW PROCESS o SHOW VECTOR_MODE o STEP/VECTOR_INSTRUCTION, /INSTRUCTION[=(opcode[,...])] o SYNCHRONIZE VECTOR_MODE See the VMS Debugger Manual for complete information about these commands and qualifiers.
DECwindows Interface: Enhancements to Menus and Dialog Boxes
The following list identifies new features for the debugger's
DECwindows interface:
o The Control menu has a new menu item labeled Synchronize
Vector Processor. This item is the DECwindows equivalent of
the command SYNCHRONIZE VECTOR_MODE.
o In the Step dialog box, the target (upper right) option menu
has a new entry labeled the next vector instruction.
o In the Break dialog box, the target (upper right) option menu
has a new entry labeled every vector instruction.
o The Call dialog box has a new toggle button labeled Save Vector
State.
o The Examine Variable dialog box has a new option menu labeled
Mask. This menu has three options labeled None, Tmask, and
Fmask.
o The Examine Code dialog box has a new option menu labeled With
Operand Values. This menu has 7 options labeled None, Brief,
Full, Brief with Tmask, Brief with Fmask, Full with Tmask, and
Full with Fmask.
o The Examine Address or Register dialog box has a new option
menu labeled Mask. This menu has three options labeled None,
Tmask, and Fmask.
o The Other Attributes dialog box has a new toggle button labeled
Scalar-Vector Synchronization. This button is equivalent to the
command SET VECTOR_MODE [NO]SYNCHRONIZED.
See the online help that is available from the debugger's
DECwindows interface for complete information about these
features.
Utility Routines:MAIL
The callable interface to the VMS MAIL utility allows you to
create applications that perform various MAIL utility functions
such as sending mail messages to users on your system. In
addition, your applications can communicate with users on remote
nodes connected to your system with DECnet-VAX.
Mail Utility Routines
Routine Description
Mail File Context
MAIL$MAILFILE_BEGIN Initiates mail file processing
MAIL$MAILFILE_CLOSE Closes a mail file
MAIL$MAILFILE_COMPRESS Compresses a mail file
MAIL$MAILFILE_END Terminates mail file processing
MAIL$MAILFILE_INFO_FILE Obtains information about the mail file
MAIL$MAILFILE_MODIFY Changes the wastebasket folder name
MAIL$MAILFILE_OPEN Opens a mail file
MAIL$MAILFILE_PURGE_WASTE Purges a mail file
Message Context
MAIL$MESSAGE_BEGIN Initiates message processing
MAIL$MESSAGE_COPY Copies messages
MAIL$MESSAGE_DELETE Deletes messages
MAIL$MESSAGE_END Terminates message processing
MAIL$MESSAGE_GET Retrieves a message
MAIL$MESSAGE_INFO Obtains information about a specified
message
MAIL$MESSAGE_MODIFY Identfies a message as replied, new, or
marked
MAIL$MESSAGE_SELECT Selects a message or messages from the
currently open mail file
Send Context
MAIL$SEND_ABORT Aborts a send operation
MAIL$SEND_ADD_ADDRESS Adds an addressee to the address list
MAIL$SEND_ADD_ATTRIBUTE Constructs the message header
MAIL$SEND_ADD_BODYPART Constructs the body of the message
MAIL$SEND_BEGIN Initiates send processing
MAIL$SEND_END Terminates send processing
MAIL$SEND_MESSAGE Sends a message
User Context
MAIL$USER_BEGIN Initiates user profile context
MAIL$USER_DELETE_INFO Deletes a user profile entry
MAIL$USER_END Terminates user profile context
MAIL$USER_GET_INFO Retrieves information about a user from
the user profile
MAIL$USER_SET_INFO Adds or modifies a user profile entry
See the VMS Utility Routines Manual for more information about the
VMS MAIL callable interface.
System Services
The VMS Version 5.4 operating system includes new and modified system services that support the following: o DECdtm services o Security enhancements o Vector processing o Volume shadowing
Additional information available:
New System Services-SummaryModified System ServicesImplementing Site-Specific Security Policies
New System Services-Summary
These are the system services that are new for the VMS Version 5.4
release.
DECdtm Services
$ABORT_TRANS - Abort Transaction
Aborts a transaction; it can be called before the transaction is
committed.
$ABORT_TRANSW - Abort Transaction and Wait
Synchronous equivalent of $ABORT_TRANS
$END_TRANS - End Transaction
Commits a transaction asynchronously
$END_TRANSW - End Transaction and Wait
Synchronous equivalent of $END_TRANS
$START_TRANS - Start Transaction
Starts a transaction (asynchronously) by allocating a transaction
identifier (TID) and establishing the internal structures that
define a transaction.
$START_TRANSW - Start Transaction and Wait
Synchronous equivalent of $START_TRANS
System Security Services
$FORMAT_AUDIT - Format Security Audit Event Message
Converts a security auditing event message from binary format to
ASCII text and filters information considered too sensitive to
display.
$HASH_PASSWORD - Hash Password
Applies a hash algorithm to an ASCII password string and returns a
quadword hash value that represents the encrypted password.
Vector Processing Services
$RELEASE_VP - Release Vector Processor
Terminates the current process's status as a vector consumer.
$RESTORE_VP_EXCEPTION - Restore Vector Processor Exception State
Restores the saved exception state of the vector processor.
$RESTORE_VP_STATE - Restore Vector State
Allows an AST routine or condition handler to restore the vector
state of the mainline routine.
$SAVE_VP_EXCEPTION - Save Vector Processor Exception State
Saves the pending exception state of the vector processor.
Modified System Services
The following system services have been modified to reflect new
VMS Version 5.4 functionality.
o $CHANGE_ACL
To control use of a system's vector processors, $CHANGE_ACL
supports a new CAPABILITY object type, which describes a
restricted resource. If the object type is CAPABILITY, use the
reserved name VECTOR, governing the ability of a subject to
access a vector processor in the system. The symbolic name is
ACL$C_CAPABILITY. The $CHANGE_ACL service also accepts new item
codes and status codes.
o $CHECK_ACCESS
Like $CHANGE_ACL, $CHECK_ACCESS also supports the new CAPABILITY
object type. Also note that $CHECK_ACCESS requires privilege to
access the UAF, for example, SYSPRV. The $CHECK_ACCESS service
also returns new status codes.
o $ENQ
$ENQ includes two new flags, LCK$M_EXPEDITE and LCK$M_QUECVT,
that enable you to expedite lock requests and force queueing of
conversions.
o $GETDVI
In Version 5.4 of the VMS operating system, $GETDVI accepts
three new device classes
o $GETJPI
In Version 5.4 of the VMS operating system, $GETJPI accepts new
item codes related to security and vector processing.
o $GETSYI
In Version 5.4 of the VMS operating system, $GETSYI accepts new
item codes related to security and vector processing.
o $GETUAI
In Version 5.4 of the VMS operating system, $GETUAI accepts new
security-related item codes.
o $MOD_IDENT
In Version 5.4 of the VMS operating system, $MOD_IDENT accepts a
new status code, SS$_DUPIDENT, which means the specified
identifier value already exists.
o $MOUNT
In Version 5.4 of the VMS operating system, $MOUNT accepts new
volume shadowing flags.
o $SETUAI
In Version 5.4 of the VMS operating system, $SETUAI accepts new
security-related item codes.
Additional information available:
$CHANGE ACL Item and Status Codes$CHECK ACCESS Status Codes$ENQ: Enhanced Lock Manager Support Flags
$GETDVI: New Device Classes$GETJPI Security-related Item CodesGET$JPI Vector-related Item Codes
$GETSYI Security-related Item Code$GETSYI Vector-related Item Codes$GETUAI Security-related Item Codes
$MOUNT Volume Shadowing Flags$SETUAI Security-related Item Codes
$CHANGE ACL Item and Status Codes
In Version 5.4 of the VMS operating system, $CHANGE_ACL accepts
the following item codes:
ACL$C_DELETE_ALL
When you specify ACL$C_DELETE_ALL, $CHANGE_ACL deletes the entire
Access Control List (ACL), including protected entries.
ACL$C_GRANT_ACE
When you specify ACL$C_GRANT_ACE, $CHANGE_ACL reads the next ACE
that matches the process' identifiers into the buffer pointed to
by bufadr. The returned ACE might grant or deny access to the
object. Since an ACL can have more than one matching ACE, you
should proceed as follows:
1. Specify an initial value of zero (0) for contxt.
2. Call $CHANGE_ACL repeatedly, without changing the value of
contxt, and test for the return status SS$_NOMOREACE, which
means that the ACL has no more matching entries.
ACL$C_NEXT_ACE
When you specify ACL$C_NEXT_ACE, $CHANGE_ACL advances through an
ACL, one ACE at a time. The contxt argument defines the initial
and final positions. The value of contxt itself is derived from
the previous ACL$C_FNDACETYP, ACL$C_FNDACLENT, or ACL$C_GRANT_ACE
operation.
The $CHANGE_ACL service returns the following new status codes:
SS$_NOPRIV You do not have privileges for the requested
action.
SS$_INCONOLCK VMS encountered an irrecoverable error. Please
submit a Software Performance Report (SPR)
that describes conditions leading to the
error.
$CHECK ACCESS Status Codes
The $CHECK_ACCESS service returns the following new status codes:
SS$_INSFMEN Identifiers granted to the user exceed the
number allowed.
SS$_NOCALLPRV Caller lacks privilege for attempted
operation.
SS$_NOSUCHSEC The specified global section does not exist.
SS$_UNSUPPORTED Operations on remote object are not supported.
$ENQ: Enhanced Lock Manager Support Flags
The addition of the following new flags to $ENQ enables you to
expedite lock requests and force queueing of conversions.
LCK$M_EXPEDITE
This flag is only valid for new lock requests. Specifying this
flag allows a request to be granted immediately, provided the
requested mode, when granted, would not block any currently queued
requests in the resource conversion and wait queues. Currently,
this flag is only valid for NLMODE requests. If this flag is
specified for any other lock mode, the request will be failed
and an error of SS$_UNSUPPORTED returned.
LCK$M_QUECVT
This flag is only valid for conversion operations. A conversion
request with the LCK$M_QUECVT flag set will be forced to wait
behind any already queued conversions.
The conversion request is granted immediately, if there are no
already queued conversions.
The QUECVT behavior is only valid for a subset of all possible
conversions. Illegal conversion requests are failed with
SS$_BADPARAM returned.
Legal set of conversion requests for LCK$M_QUECVT
Lock Mode Lock Mode to Which Lock Is Converted
at Which
Lock Is
Held NL CR CW PR PW EX
NL No Yes Yes Yes Yes Yes
CR No No Yes Yes Yes Yes
CW No No No Yes Yes Yes
PR No No Yes No Yes Yes
PW No No No No No Yes
EX No No No No No No
__________________________________________________________________
Key to Lock Modes
NL-Null lock
CR-Concurrent read
CW-Concurrent write
PR-Protected read
PW-Protected write
EX-Exclusive lock
$GETDVI: New Device Classes
In Version 5.4 of the VMS operating system, $GETDVI accepts the following three new device classes: Values Returned by the DEVCLASS Item Device Class Value Symbolic Name Workstation 70 DC$_WORKSTATION DECvoice 97 DC$_DECVOICE Remote console 170 DC$_REMCSL_STORAGE storage
$GETJPI Security-related Item Codes
In Version 5.4 of the VMS operating system, $GETJPI accepts the
following new item codes and returns information about process
security characteristics.
JPI$_RIGHTS_SIZE
When you specify JPI$_RIGHTS_SIZE, $GETJPI returns the number of
bytes required to buffer the rights list. The rights list includes
both the system rights list and the process rights list. Because
the space requirements for the rights list can change between
the time you request the size of the rights list and the time
you store the rights list with JPI$_RIGHTSLIST, you might want to
allocate a buffer that is 10% larger.
JPI$_PROCESS_RIGHTS
When you specify JPI$_PROCESS_RIGHTS, $GETJPI returns the binary
content of the process rights list as an array of quadword
identifiers. Each entry consists of a longword identifier value
and longword identifier attributes. Allocate a buffer that is
sufficient to hold the process rights list because $GETJPI only
returns as much of the list as will fit in the buffer.
Table - Attributes of an Identifier
Symbolic Name Description
KGB$M_RESOURCE Resources can be charged to the identifier.
KGB$M_DYNAMIC Identifier can be enabled or disabled.
JPI$_SYSTEM_RIGHTS
When you specify JPI$_SYSTEM_RIGHTS, $GETJPI returns the system
rights list as an array of quadword identifiers. Each entry
consists of a longword identifier value and longword identifier
attributes, shown in the attributes table. Allocate a buffer that
is sufficient to hold the system rights list because $GETJPI only
returns as much of the list as will fit in the buffer.
JPI$_RIGHTSLIST
When you specify JPI$_RIGHTSLIST, $GETJPI returns, as an array of
quadword identifiers, all identifiers applicable to the process.
This includes the process rights list (JPI$_PROCESS_RIGHTS) and
the system rights list (JPI$_SYSTEM_RIGHTS). Each entry consists
of a longword identifier value and longword identifier attributes
shown in the attribute table. Allocate a buffer that is sufficient
to hold the rights list because $GETJPI only returns as much of
the list as will fit in the buffer.
JPI$_LAST_LOGIN_I
When you specify JPI$_LAST_LOGIN_I, $GETJPI returns, as a quadword
absolute time value, the date of the last successful, interactive
login prior to the current session. It returns a quadword of 0
when processes have not executed the LOGINOUT image.
JPI$_LAST_LOGIN_N
When you specify JPI$_LAST_LOGIN_N, $GETJPI returns, as a
quadword absolute time value, the date of the last successful,
noninteractive login prior to the current session. It returns a
quadword of 0 when processes have not executed the LOGINOUT image.
JPI$_LOGIN_FAILURES
When you specify JPI$_LOGIN_FAILURES, $GETJPI returns the number
of login failures that occurred prior to the current session.
It returns a longword of 0 when processes have not executed the
LOGINOUT image.
JPI$_LOGIN_FLAGS
When you specify JPI$_LOGIN_FLAGS, $GETJPI returns a longword
bitmask containing information related to the login sequence.
It returns a longword of 0 when processes have not executed the
LOGINOUT image. The following bits are defined:
Symbolic Name Description
JPI$M_NEW_MAIL_AT_LOGIN User had new mail messages waiting at
login.
JPI$M_PASSWORD_CHANGED User changed the primary password
during login.
JPI$M_PASSWORD_EXPIRED User's primary password expired
during login.
JPI$M_PASSWORD_WARNING System gave the user a warning at
login that the account's primary
password would expire within 5 days.
JPI$M_PASSWORD2_CHANGED Account's secondary password was
changed during login.
JPI$M_PASSWORD2_EXPIRED Account's secondary password expired
during login.
JPI$M_PASSWORD2_WARNING System gave the user a warning at
login that the account's secondary
password would expire within 5 days.
GET$JPI Vector-related Item Codes
In Version 5.4 of the VMS operating system, $GETJPI accepts the following item codes and returns information regarding a process's use of system vector processing resources. JPI$_FAST_VP_SWITCH When you specify JPI$_FAST_VP_SWITCH, $GETJPI returns an unsigned longword containing the number of times this process has issued a vector instruction that resulted in an inactive vector processor being enabled without the expense of a vector context switch. In other words, this count reflects those instances in which the process has reenabled a vector processor on which the process's vector context has remained intact. JPI$_SLOW_VP_SWITCH When you specify JPI$_SLOW_VP_SWITCH, $GETJPI returns an unsigned longword containing the number of times this process has issued a vector instruction that resulted in an inactive vector processor being enabled with a full vector context switch. This vector context switch involves the saving of the vector context of the process that last used the vector processor and the restoration of the vector context of the current process. JPI$_VP_CONSUMER When you specify JPI$_VP_CONSUMER, $GETJPI returns a byte, the low-order bit of which, when set, indicates that the process is a vector consumer. JPI$_VP_CPUTIM When you specify JPI$_VP_CPUTIM, $GETJPI returns an unsigned longword that contains the total amount of time the process has accumulated as a vector consumer.
$GETSYI Security-related Item Code
In Version 5.4 of the VMS operating system, $GETSYI accepts the following item code and returns information about system security. SYI$_SYSTEM_RIGHTS When you specify SYI$_SYSTEM_RIGHTS, $GETSYI returns the system rights list as an array of quadword identifiers. Each entry consists of a longword identifier value and the following longword identifier attributes: Symbolic Name Description KGB$M_RESOURCE Resources can be charged to the identifier. KBG$M_DYNAMIC Identifier can be enabled or disabled. Allocate a buffer that is sufficient to hold the system rights list because $GETSYI only returns as much of the list as will fit in the buffer.
$GETSYI Vector-related Item Codes
In Version 5.4 of the VMS operating system, $GETSYI accepts the following item codes and returns information regarding the system's vector processing configuration. SYI$_VP_MASK When you specify SYI$_VP_MASK, $GETSYI returns a longword mask, the bits of which, when set, indicate which processors in the system have vector coprocessors. SYI$_VP_NUMBER When you specify SYI$_VP_NUMBER, $GETSYI returns an unsigned longword containing the number of vector processors in the system. SYI$_VECTOR_EMULATOR When you specify SYI$_VECTOR_EMULATOR, $GETSYI returns a byte, the low-order bit of which, when set, indicates the presence of the VAX vector instruction emulator facility (VVIEF) in the system.
$GETUAI Security-related Item Codes
In Version 5.4 of the VMS operating system, $GETUAI accepts the
following item codes and returns information about passwords and
logins.
UAI$_ENCRYPT
When you specify UAI$_ENCRYPT, $GETUAI returns one of the values
shown in the following table, identifying the encryption algorithm
for the primary password.
Because the encryption algorithm is a byte in length, the buffer
length field in the item descriptor should specify 1 byte.
Symbolic Name Description
UAI$C_AD_II Uses a CRC algorithm and returns a longword
hash value. It was used in VMS releases
prior to Version 2.0.
UAI$C_PURDY Uses a Purdy algorithm over salted input. It
expects a blank-padded user name and returns
a quadword hash value. The algorithm was
used during VMS Version 2.0 field test.
UAI$C_PURDY_V Uses the Purdy algorithm over salted input.
It expects a variable length user name and
returns a quadword hash value. The algorithm
was used in VMS releases prior to Version
5.4.
UAI$C_PURDY_S Uses the Purdy algorithm over salted input.
It expects a variable length user name and
returns a quadword hash value. This is the
current algorithm that VMS uses for all new
password changes.
UAI$_ENCRYPT2
When you specify UAI$_ENCRYPT2, $GETUAI returns one of the
following values identifying the encryption algorithm for the
secondary password. Please refer to the UAI$_ENCRYPT item code for
a description of the algorithms.
- UAI$C_AD_II
- UAI$C_PURDY
- UAI$C_PURDY_V
- UAI$C_PURDY_S
Because the encryption algorithm is a byte in length, the buffer
length field in the item descriptor should specify 1 byte.
UAI$_FLAGS
This item code has two new symbolic names:
Symbolic Name Description
UAI$V_DISPWDDIC Automatic checking of user-selected passwords
against the system dictionary is disabled.
UAI$V_DISPWDHIS Automatic checking of user-selected passwords
against previously used passwords is disabled.
$MOUNT Volume Shadowing Flags
The following flags have been added to the Mount system service
for V5.4. For more information about volume-shadowing, see the
VMS Volume Shadowing Manual.
MNT$V_INCLUDE Applicable only if you have the VMS
Volume Shadowing option.
MNT$V_NOCOPY Applicable only if you have the VMS
Volume Shadowing option.
MNT$V_OVR_SHAMEM Applicable only if you have the VMS
Volume Shadowing option.
$SETUAI Security-related Item Codes
Starting with VMS Version 5.4, passwords selected by users can
be screened for acceptability. The VMS system automatically
compares new passwords against a system dictionary to ensure that
a password is not a native language word. It also maintains a
history list of a user's passwords and compares each new password
against this list to guarantee that an old password is not reused.
In addition, a site with contractual obligations to use special
algorithms for encrypting passwords will be able to use them.
To support these enhancements, $SETUAI accepts the following new
or modified item codes.
UAI$_ENCRYPT
When you specify UAI$_ENCRYPT, $SETUAI sets one of the values
shown in the following table to identify the encryption algorithm
for the primary password.
Symbolic Name Description
UAI$C_AD_II Uses a CRC algorithm and returns a longword
hash value. It was used in VMS releases
prior to Version 2.0.
UAI$C_PURDY Uses a Purdy algorithm over salted input.
It expects a blank-padded user name
and returns a quadword hash value. The
algorithm was used during VMS Version 2.0
field test.
UAI$C_PURDY_V Uses the Purdy algorithm over salted input.
It expects a variable length user name
and returns a quadword hash value. The
algorithm was used in VMS releases prior to
Version 5.4.
UAI$C_PURDY_S Uses the Purdy algorithm over salted input.
It expects a variable length user name and
returns a quadword hash value. This is the
current algorithm that VMS uses for all new
password changes.
UAI$C_PREFERED_ Represents the latest encryption algorithm
ALGORITHM that the VMS system uses to encrypt new
passwords. Currently, it equates to UAI$C_
PURDY_S. Digital recommends that you use
this symbol in source modules.
Because the encryption algorithm is a byte in length, the buffer
length field in the item descriptor should specify 1 byte.
UAI$_ENCRYPT2
When you specify UAI$_ENCRYPT2, $SETUAI sets one of the following
values, indicating the encryption algorithm for the secondary
password. Please refer to the UAI$_ENCRYPT item code for a
description of the algorithms.
- UAI$C_AD_II
- UAI$C_PURDY
- UAI$C_PURDY_V
- UAI$C_PURDY_S
- UAI$C_PREFERED_ALGORITHM
Because the encryption algorithm is a byte in length, the buffer
length field in the item descriptor should specify 1 byte.
UAI$_FLAGS
This item code has two new symbolic names:
Symbolic Name Description
UAI$V_DISPWDDIC Automatic checking of user-selected passwords
against the system dictionary is disabled.
UAI$V_DISPWDHIS Automatic checking of user-selected passwords
against previously used passwords is disabled.
UAI$_SALT
When you specify UAI$_SALT, $SETUAI sets the salt field of the
user's record to the value you provide. The salt value is used
in the VMS hash algorithm to generate passwords. $SETUAI does not
generate a new salt value for you.
Because this decimal number is a word in length, the buffer length
field in the item descriptor should specify 2 bytes.
By copying the item codes UAI$_SALT, UAI$_ENCRYPT, UAI$_PWD,
UAI$_PWD_DATE, and UAI$_FLAGS, a site-security administrator can
construct a utility that propagates password changes throughout
the network. Please note, however, that DIGITAL does not recommend
using the same password on more than one node in a network.
Implementing Site-Specific Security Policies
For VMS Version 5.4 you can write routines that implement site- specific policies or special algorithms. The routines that you write can either replace or augment the built-in VMS policies.
Additional information available:
Creating Loadable Security ServicesInstalling Site-Specific Password Policy Filters
Creating Loadable Security Services
You can prepare a system service image and update the file SYS$LOADABLE_IMAGES:VMS$SYSTEM_IMAGES.DATA, which controls site-specific loading of system images. Currently, you can replace three system services with services specific to your site: o $ERAPAT-generates a security erase pattern o $MTACCESS-controls magnetic tape access o $HASH_PASSWORD-applies a hash algorithm to an ASCII password When creating the system service, you code the source module and define the vector offsets, the entry point, and the program sections for the system service. At this point you can assemble and link the module to create a loadable image. Once created, you install the loadable image. First you copy the image into the SYS$LOADABLE_IMAGES directory and add an entry for it in the VMS system images file using the SYSMAN Utility. Then you invoke the system images command procedure to generate a new system image data file. Finally, you reboot the system to load in your service.
Installing Site-Specific Password Policy Filters
For VMS Version 5.4 a site security administrator (SSA) can screen new passwords to ensure that they comply with a site-specific password policy. A security administrator can encode the policy, create a shareable image and install it in SYS$LIBRARY, and, finally, enable the policy by setting a SYSGEN parameter.
Run-Time Library Routines
For Version 5.4 of the VMS operating system, there are new routines for the RTL Parallel Processing (PPL$) facility and the RTL Math (MTH$) facility.
Additional information available:
Parallel Processing (PPL$)Mathematics (MTH$)
Parallel Processing (PPL$)
The VMS Version 5.4 RTL Parallel Processing (PPL$) facility
contains 19 new routines that complement the basic suite of
functionality originally provided for VMS Version 5.0. New
features of the PPL$ facility include the following:
o A routine, PPL$CREATE_APPLICATION, that informs the PPL$
facility that the caller is forming or joining a parallel
application. This routine replaces PPL$INITIALIZE, which is
obsolete as of VMS V5.4.
o Routines that implement work queues. Work queues allow one
or more processes to serve as dispatchers of work items to be
performed by other processes. Work queues also provide process
synchronization.
Routines that implement work queue synchronization are as
follows:
PPL$CREATE_WORK_QUEUE
PPL$DELETE_WORK_QUEUE
PPL$READ_WORK_QUEUE
PPL$DELETE_WORK_ITEM
PPL$INSERT_WORK_ITEM
PPL$REMOVE_WORK_ITEM
A new example program written in VAX C shows the use of the
work queue routines and PPL$CREATE_APPLICATION.
o Routines that delete a PPL$ application or object. These
routines are as follows:
PPL$DELETE_APPLICATION
PPL$DELETE_BARRIER
PPL$DELETE_EVENT
PPL$DELETE_SEMAPHORE
PPL$DELETE_SPIN_LOCK
PPL$DELETE_VM_ZONE
o Routines that set and adjust a semaphore maximum (analogous to
setting and adjusting a barrier quorum). These routines are as
follows:
PPL$ADJUST_SEMAPHORE_MAXIMUM
PPL$SET_SEMAPHORE_MAXIMUM
o Routines that disable event notification and reset an event
state ("untrigger" an event). These routines are as follows:
PPL$DISABLE_EVENT
PPL$RESET_EVENT
o Routines that read a spin lock state and find a synchronization
element or shared memory zone's identifier, as follows:
PPL$READ_SPIN_LOCK
PPL$FIND_OBJECT_ID
PPL$FIND_OBJECT_ID replaces PPL$FIND_SYNCH_ELEMENT_ID, which is
obsolete as of VMS V5.4.
For a detailed description of the new PPL$ routines, refer to the
VMS RTL Parallel Processing (PPL$) Manual.
Mathematics (MTH$)
The RTL MTH$ facility provides the following new and modified sets
of routines to support vector processing:
o Basic Linear Algebra Subroutines (BLAS) Level 1
o First Order Linear Recurrence (FOLR)
o Routines that have been vectorized to support Digital
vectorizing compilers such as the VAX FORTRAN High Performance
Option (HPO)
See documentation on vector processing for more information about
using RTL MTH$ routines in a vector processing environment. See
VMS RTL Mathematics (MTH$) Manual for complete descriptions about
all new, modified, and existing RTL MTH$ routines.
*********************Edits to here************
VMS Record Management Services
VMS Version 5.4 of the operating system includes the following enhancements to the VMS Record Management Services: o Asynchronous support for process-permanent files o Increase in local buffer limit o Access-mode protection o Expired Date Suppression
Additional information available:
VMS RMS Asynchronous Support for Process-Permanent FilesLocal Buffer Maximum Increased
Access-Mode Protection for VMS RMSExpired Date Suppression
VMS RMS Asynchronous Support for Process-Permanent Files
Prior to Version 5.4 of the VMS operating system, VMS RMS ignored the asynchronous option for process-permanent files. VMS RMS now supports this option, which affects the performance options within the following two RMS control blocks: RMS Control Block Field Performance Option File Access Block (FAB) FAB$L_FOP FAB$V_ASY Record Access Block (RAB) RAB$L_ROP RAB$V_AST
Local Buffer Maximum Increased
With Version 5.4 of the VMS operating system, the maximum number of local buffers is increased to 32,767. Prior to Version 5.4, you were limited to specifying no more than 127 local buffers for a record stream from the VMS RMS interface using the RAB multibuffer count field (RAB$B_MBF). You obtain the additional local buffering capability by using the multibuffer count XABITM. The multibuffer count XABITM is used as an input to the Connect service only. It is not used as an output by any service. The maximum number of local buffers established by the DCL command SET RMS_DEFAULT for a process has also increased from 127 to 255. However, the maximum number of local buffers established by the DCL command SET RMS_DEFAULT for the system remains 127. The XAB$_MULTIBUFFER_COUNT XABITM requires a 4-byte buffer to store the value that specifies the number of local buffers. To specify the number of local buffers, set up the XAB$_MULTIBUFFER_ COUNT XABITM with the number of local buffers desired. Then, link the XABITM into the XAB chain for the record stream prior to invoking the Connect service. When you use the multibuffer count XABITM, the value specified overrides any value that resides in the RAB$_MBF for the related record stream. See Chapter 11 of the VMS Record Management Services Manual for details about using an XABITM. Before you increase the size of the local buffer pool, you should consider current memory management parameters because excessively large buffer pools introduce additional paging that can reduce I/O performance. See the VMS Record Management Services Manual for details.
Access-Mode Protection for VMS RMS
VMS RMS now provides access-mode protection for its services and
associated memory. This feature is analogous to the protection
provided by the system services $ASSIGN and $SETPRT.
No code changes are required for RMS calls involving a single
access mode. A code change might be required for RMS calls that
initiate operations from an inner access mode and allow subsequent
RMS operations from an outer access mode.
If an inner-mode caller initiates an RMS operation without
overriding the access mode, subsequent outer-mode calls fail with
an RMS$_PRV error. The arguments in the following code example
are used to override the caller's access mode. These arguments,
together with related topics, are described in the section on
access modes in Introduction to VMS System Services.
FAB$V_CHAN_MODE = PSL$C_<USER,SUPER,EXEC,KERNEL> ! Select one
VMS uses the maximized value of the caller's access-mode and the
FAB$V_CHAN_MODE argument (RMS access-mode argument) to establish
the access mode.
Additional information available:
Access-Mode Protected ServicesAccess-Mode Protected Memory
Access-Mode Protected Services
The following services initiate operations on files. These services establish the access mode which VMS RMS uses to validate the access modes of subsequent accessing services. $CREATE $OPEN $PARSE $SEARCH The following services access open files to perform various VMS RMS operations. The access modes for each services trying to access an open file must be validated before RMS operations are allowed. $CLOSE $CONNECT $DELETE $DISCONNECT $DISPLAY $EXTEND $FIND $FREE $FLUSH $GET $NXTVOL $PUT $READ $RELEASE $REWIND $SPACE $TRUNCATE $UPDATE $WAIT $WRITE VMS RMS does not validate the access mode for the following services because access-mode comparison is not relevant to them. $ENTER $ERASE $REMOVE $RENAME
Access-Mode Protected Memory
VMS RMS now protects the following data structures and their associated I/O buffers at EW (executive read/write). Previously, the data structures were protected at UREW (user read, executive write). o RMS-controlled data structures o Process-permanent data structures o Image-activated data structures The following memory protection exceptions apply to user-mode accessors of RMS and are protected at UREW: o Internal RMS I/O buffers-to facilitate RAB$V_LOC mode o RMS buffers containing collated tables used for indexed files
Expired Date Suppression
The file system, in conjunction with parameters established using the DCL interface (see the Set Volume command in VMS DCL Dictionary), gives users a facility for determining whether a data file has expired and is eligible to be transferred to another storage medium. Expiration of a file is determined by the Expiration Date and Time, which should not be updated for maintainance functions or for any function where the data is not really being modified. Prior to VMS Version 5.4, the ability to suppress the expiration update was available only to applications that interface directly with the file system through the $QIO system service. (See ACP Functions in VMS I/O User's Reference Manual: Part I). Now the ability to selectively suppress the update of the Expiration Date and Time is available to all applications through the RMS interface.
Additional information available:
The Role of XAB$ NORECORD XABITMApplications of XAB$ NORECORD XABITM
The Role of XAB$ NORECORD XABITM
The XAB$_NORECORD XABITM suppresses the update of the Expiration Date and Time on the $CLOSE service. The Expiration Date and Time is used by VMS to determine if the data in a disk file has been accessed recently. Normally, when data has been read or written to a disk file, the $CLOSE service updates the Expiration Date and Time to the current date and time. This moves back the date and time when the file is considered expired. Specifying the XAB$_ NORECORD XABITM suppresses the update of the Expiration Date and Time. The XAB$_NORECORD XABITM uses a 4-byte buffer to set the NORECORD flag to logic 1 using the symbol XAB$_ENABLE. Any other value in this XABITM buffer returns an RMS$_XAB error. An application cannot disable this option because the ODS-II ACP does not support disabling this function once it has been selected on a $OPEN or $CREATE.
Applications of XAB$ NORECORD XABITM
Typically, the XAB$_NORECORD XABITM is used by directory or maintenance routines that do not manipulate the data and, therefore, does not change the expiration status of a disk file. For example, the DCL command DIRECTORY/FULL uses the XAB$_NORECORD XABITM as it opens files to access prolog data containing key information. In this case, DIRECTORY displays prolog information but does not display or modify user data in the disk file and should not modify the Expiration Date and Time. Maintenance utilities should consider using this XABITM. For example, a disk defragmentation utility should not modify the expiration status of a disk file. Digital recommends using the XAB$_NORECORD XABITM on the $OPEN service instead of on the $CLOSE service-because the suppression of the Expiration Date and Time update is guaranteed should the file deaccess or should a close occur because of process deletion or RMS rundown. XAB$_NORECORD can be enabled on input to the $CLOSE, $OPEN and $CREATE services. If the $CREATE service opens an existing file through the Create-if option and the Expiration Date and Time are not to be modified, the XAB$_NORECORD XABITM can be specified. When the XAB$_NORECORD XABITM is used on a $CREATE that creates a file, it disables the update on the subsequent $CLOSE but does not prevent initialization of the Expiration Date and Time on the file creation in the ACP. The XAB$_NORECORD XABITM can be sensed on output from RMS for the $OPEN, $CREATE, $DISPLAY and $CLOSE services. An application typically senses the XAB$_NORECORD XABITM to determine if the XABITM was specified on a previous $OPEN or $CREATE option or if it is specified by the current RMS operation.
VAX RMS Journaling
For Version 5.4 of the VMS operating system, VAX RMS Journaling includes features that allow you to take advantage of the new DECdtm services. It also continues to support existing applications based on previous versions of VAX RMS Journaling.
Additional information available:
Support for DECdtm TransactionsRUF Services EmulatedNetwork Support
Record Stream AssociationDetached RecoveryPlacement of Recovery Unit Journals
Multiple Long-Term Journals AllowedMixed-Version Clusters
Support for DECdtm Transactions
The DECdtm transaction has superseded the Recovery Unit Facility (RUF) recovery unit. In VAX RMS Journaling Version 5.4, an RMS recovery unit is the recoverable work performed by a single process within a DECdtm transaction. The RUF recovery unit services have been superseded by corresponding DECdtm transaction services as follows: RUF Recovery Unit Service DECdtm Transaction Service $START_RU $START_TRANS(W) $END_RU $END_TRANS(W) $ABORT_RU $ABORT_TRANS(W) In addition, a single DECdtm transaction service, $END_TRANS(W), has replaced two other RUF services, $PREPARE_RU and $COMMIT_RU, which together were equivalent to the $END_RU service.
RUF Services Emulated
Recovery Unit Facility (RUF) services are still supported. They are transparently emulated using DECdtm transaction services. You do not have to recompile or relink your applications to run them under VAX RMS Journaling Version 5.4. You can convert an application that uses only one active transaction at a time to use the DECdtm services by replacing calls to RUF services with calls to the corresponding DECdtm transaction services. However, combining DECdtm transaction services and RUF recovery unit services in a single image requires care. You should avoid having transactions that were started using the DECdtm services active at the same time as transactions that were started using the RUF services.
Network Support
Remote RMS files that are marked for recovery unit journaling
can be modified within a transaction. They will be included in
the "atomic unit of work" defined by the transaction. A "remote"
file is a file accessed by a "client" RMS process via the DAP/FAL
protocol to a "server" system.
The following conditions apply to remote files:
o Remote files can be marked for any combination of RU, AI, or BI
journaling.
o All journaling takes place locally with respect to each file.
o All recovery takes place locally with respect to each file.
o Both client and server nodes must support DECdtm (that is, must
be running VMS Version 5.4 or later).
o The server node must be licensed for RMS Journaling.
o The DIRECTORY/FULL and ANALYZE/RMS commands have been enhanced
to display the type of journaling enabled but not the names of
any AI or BI journals.
o The SET FILE/AI_JOURNAL/BI_JOURNAL/RU_JOURNAL command can only
be applied to a locally accessed file.
Record Stream Association
In applications that use the DECdtm transaction services, an RMS record stream is associated with a transaction as a result of an RMS record operation. The application can use either the DECdtm default transaction or the new XABITM item list entry XAB$_TID to determine which transaction the record stream should join.
Additional information available:
When Do Streams Become Associated with a Transaction?Stream Association Using RUF and DECdtm Services
When Do Streams Become Associated with a Transaction?
Under RMS Journaling Version 5.4, record streams are associated
with transactions as follows:
o If the DECdtm services are being used, then eligible
streams associate with a transaction at the time of a record
operation, not when the transaction is started or the stream is
established (as was the case using RUF services).
o A record operation can cause stream association if its action
is recoverable. The $PUT, $UPDATE, $DELETE, $FIND, $FREE, $GET,
$RELEASE, and $REWIND services may cause an eligible stream to
associate with a transaction.
o A record operation must result in stream association if it
affects record data in the file. The $PUT, $UPDATE, and $DELETE
services must cause an eligible stream to be associated with a
transaction.
Stream Association Using RUF and DECdtm Services
The following example compares the way streams are associated with
transactions under DECdtm and RUF:
Using DECdtm Using RUF
$START_TRANSW $START_RU
$GET from stream1 $GET from stream1
$UPDATE to stream1 $UPDATE to stream1
o Using Version 5.4 of RMS Journaling (DECdtm services), the
stream associates on the $GET service.
o Using RUF services with versions of RMS Journaling prior to
5.4 and emulation on Version 5.4, the stream associates on the
$START_RU.
o In most cases this difference does not matter and a RUF
application can be converted to the direct use of DECdtm
services by simple substitution.
o In the cases where it does matter, the association at record
operation time is more flexible than association at transaction
start (using RUF).
Detached Recovery
Several changes have been made in the operation of detached recovery.
Additional information available:
Synchronous and Asynchronous RecoveryPartial Recovery
Synchronous and Asynchronous Recovery
The RMS Detached Recovery server (new image
SYS$SYSTEM:RMSREC$SERVER.EXE) can perform both synchronous and
asynchronous recovery. Asynchronous recovery is the default mode;
it proceeds as follows:
1. Detached recovery "adopts" orphaned transactions by acquiring
the record locks for all records modified within a recovery
unit. The detached recovery server is multithreaded and
performs asynchronous system service calls (including RMS
operations).
2. The detached recovery server indicates completion as soon as
the record locks have been reacquired. Thus access to records
and files is reenabled sooner.
3. Actual recovery proceeds asynchronously with respect to the
original request. This is in contrast to the "synchronous"
recovery that was performed in versions of VAX RMS Journaling
prior to Version 5.4.
Synchronous recovery is used in the following circumstances:
o Partial recovery: One or more secondary files are unavailable,
so detached recovery cannot acquire all the record locks
from an orphaned transaction.
o Limited resources: The detached recovery server does not have
enough resources to acquire all the record locks on the file
to be recovered (for example, a very large data base with many
active transactions).
o Exclusive access: The process that initiates detached recovery
has tried to access the file such that it either has exclusive
access to the file or it is the only process that can modify
the file. (It may or may not allow shared read access.) In this
case, the accessor will not look for record locks from other
processes, and the locks owned by detached recovery can create
difficulties for the accessor.
Partial Recovery
When detached recovery receives a request to recover a file, it tries to recover all the effects of all orphaned transactions that involve the file. The specific file for which RMS requests recovery is called the "primary" file. In addition to the changes made to the primary file, each of the orphaned transactions can also include changes to a number of other files. These additional files are called "secondary" files. Recovery of secondary files is not required in order to allow access to the primary file. If detached recovery cannot access a secondary file that is referenced in a recovery unit journal for one of the orphaned transactions, then detached recovery cannot adopt that transaction. In such a case, detached recovery recovers that particular recovery unit journal in synchronous mode and omits all operations that involve the inaccessible secondary file. Omitting a secondary file is permissible, since it is only necessary to recover the primary file to satisfy the client's request. All the information necessary to recover the secondary file is left in the recovery unit journal for eventual use in recovering that file.
Placement of Recovery Unit Journals
In RMS Journaling Version 5.4, the location of a recovery unit
journal is determined as follows:
o The first local stream that associates with the transaction
selects the location for the RUJ file.
o By default, the recovery unit journal is on the same volume as
the file.
o The SET FILE/RU_JOURNAL=(LABEL=parameter(volnam)) command can
specify a different volume for all accessors of the file.
o Each accessor can redirect the recovery unit journal by
defining a different equivalence name for the logical
DISK$parameter(volnam). (New)
o The XAB$_RUJVOLNAM item list entry on a XABITM block connected
to the RAB can be used to override all the preceding factors.
(New)
o Recovery unit journals can be reused. When the transaction is
completed, the recovery unit journal becomes idle.
o If the process does not have an idle recovery unit journal on
the selected volume, then a new one is created.
The following example compares the placement of a recovery unit
journal under DECdtm and RUF:
Using DECdtm Using RUF
$START_TRANSW $START_RU
$GET from parameter(stream1) $GET from parameter(stream1)
$UPDATE to parameter(stream1) $UPDATE to parameter(stream1)
o Using VAX RMS Journaling Version 5.4 (DECdtm services), the
recovery unit journal is created when the $GET service is
called.
o Using a version of VAX RMS Journaling prior to Version 5.4
(that is, RUF services), the recovery unit journal is created
when the $UPDATE service is called.
o Using RUF emulation on Version 5.4, the recovery unit journal
is created when the $START_RU service is called.
o Under Version 5.4, even read-only transactions require a
recovery unit journal, but it will not be written to.
Multiple Long-Term Journals Allowed
The files involved in a single transaction are no longer restricted to a single after-image journal and a single before- image journal.
Mixed-Version Clusters
Nodes using versions of VAX RMS Journaling prior to Version 5.4
can run together in a VAXcluster with nodes using Version 5.4.
Shared access to files marked for journaling is supported in such
a mixed-version cluster with one exception: you cannot use a node
running an earlier version to recover a file that participated in
a transaction that required a two-phase commit. VAX RMS Journaling
Version 5.4 includes certain records ("prepare" records) in the
journal that earlier versions do not understand.
I O Driver Support
VMS Version 5.4 of the operating system provides new and enhanced I/O Driver support.
Additional information available:
Pseudoterminal DriverShadow Set Virtual Unit DriverNew Modifier Bits for TRM$ MODIFIERS Item Code
Itemlist Read Function I O Status BlockNew ACP-QIO Function AttributesDEMNA Ethernet 802 Controller
Pseudoterminal Driver
The Pseudo Terminal Driver (FTDRIVER) is now part of the VMS operating system. This driver, along with several control connection (PTD$) routines, enables you to create, use, and manipulate pseudoterminals with the VMS operating system. The VMS I/O User's Reference Manual: Part I describes pseudoterminal driver functions and capabilities, and lists the VAX calling standards for the control connection routines.
Shadow Set Virtual Unit Driver
The Shadow Set Virtual Unit Driver (SHDRIVER) is now part of the VMS operating system. This driver provides support for VMS Host Based Shadowing. Host Based Shadowing provides the same capabilities as standard VMS Volume Shadowing, but also supports all DSA disks. The VMS I/O User's Reference Manual: Part I describes shadow set virtual unit driver functions and capabilities.
New Modifier Bits for TRM$ MODIFIERS Item Code
Six new modifier bits have been added for the TRM$_MODIFIERS item
code for itemlist terminal driver read verify operations:
o TRM$M_TM_ARROWS-The terminal interprets the left and right
arrow keys.
o TRM$M_TM_NOCLEAR-Fill characters are not replaced with clear
characters after a non-fill character occurs.
o TRM$M_TM_OTHERWAY-Enables left-justify insert mode and right-
justify overstrike mode.
o TRM$M_TM_TERM_ARROW-The read operation is terminated when a
left or right arrow key is entered at the corresponding margin.
o TRM$M_TM_TERM_DEL-The read operation is terminated when a
DELETE key is entered at the left margin.
o TRM$M_TM_TOGGLE-Enables CTRL/A to function as a toggle key
between insert mode and overstrike mode.
Table 8-8 in the VMS I/O User's Reference Manual: Part I describes
the TRM$_ MODIFIERS item code and its associated modifier bits.
Itemlist Read Function I O Status Block
In the I/O status block (IOSB) for the itemlist read function, the byte at IOSB+5, which formerly returned -1, now returns status information. Table 8-15 in the VMS I/O User's Reference Manual: Part I lists this status information.
New ACP-QIO Function Attributes
Three new attributes for ACP-QIO functions have been added:
o ATR$_C_DELETE_ALL-Deletes the entire access control list (ACL)
o ATR$_C_GRANT_ACE-Returns an access control list entry (ACE)
which grants or denies access
o ATR$_C_NEXT_ACE-Points to the next ACE in the ACL
Table 1-3 in the VMS I/O User's Reference Manual: Part I describes
ACP-QIO function attributes.
DEMNA Ethernet 802 Controller
New Support for the XMI Bus
The VMS Version 5.4 operating system supports the DEMNA (DEC
LANcontroller 400), which is a new Ethernet/802 controller that
connects to the XMI bus. The QIO interface to the DEMNA is the
same as that described for the DEBNA device driver in the VMS I/O
Users's Reference Manual Part II, except that the device type for
the DEMNA is DT$_EX_DEMNA.
The DEMNA controller is supported by EXDRIVER. Its device name
is:
EXcu
where c is the controller and u is the unit number. For example:
EXA0:
The NCP LINE and CIRCUIT name for the DEMNA controller is as
follows:
MNA-<controller number>
For example:
MNA-0 for EXAn and MNA-1 for EXBn.
System Dump Analyzer Utility (SDA)
Version 5.4 of the VMS operating system provides two new qualifiers for SHOW PROCESS command of the SDA Utility.
Additional information available:
New SHOW PROCESS Qualifiers
/IMAGES
The /IMAGES qualifier to the SDA SHOW PROCESS command displays the
address of the Image Control Block, the starting and end addresses
of the image, the activation code, the protected and shareable
flags, the image name, and the major and minor ID of the image.
The following is an example of output displayed by the SHOW
PROCESS/IMAGES command:
Process activated images
------------------------
ICB Start End Type Image Name Major ID,Minor ID
-------- -------- -------- -------------- -----------------------------
7FF83878 00000200 00000DFF MAIN SHOW_PROC_IMAGES 0,0
7FF84100 0003AC00 0003FBFF GLOBAL PRT SHR DECW$TRANSPORT_COMMON 12,12
7FF84400 00036200 0003ABFF GLOBAL CONVSHR 1,0
7FF84470 0002E400 000361FF GLOBAL FDLSHR 1,0
7FF84560 00021A00 0002E3FF GLOBAL SORTSHR 2,28
7FF845D0 00000E00 000089FF GLOBAL LIBRTL2 1,12
7FF835F8 00008A00 000219FF GLOBAL SHR LIBRTL 1,14
7FF84800 0 00060C00 000767FF MERGED SHR ADARTL 0,0
7FF84720 00076800 000A03FF GLOBAL SHR MTHRTL 129,32781
Total images = 9 Pages allocated = 1017
The following are possible values for the activation code:
o MAIN-Image is the object of a RUN command
o MERGED-Image is an additional mapped image
o GLOBAL-Image is a global image section
The protected flag (PRT) indicates that the image is installed
protected. The shareable flag (SHR) indicates that the image is
installed shareable.
/VECTOR_REGISTERS
The System Dump Analyzer (SDA) lets you examine vector
instructions and vector context from a system dump file or in
a running system. One way to accomplish this is by specifying the
new /VECTOR_REGISTERS qualifier to the SHOW PROCESS command, which
obtains the values of the registers from the process's vector
context area.
For more information on the SDA SHOW PROCESS command, see the VMS
System Dump Analyzer Utility Manual.
Device Support
The VMS Version 5.4 release provides support for writing and debugging driver software for VAX 9000 and VAX 6000 systems and includes enhancements to several pool checking operations.
VAX Text Processing Utility (VAXTPU)
The following VAXTPU Version 2.6 new features and enhancements are
included in the Version 5.4 release of the VMS operating system.
See the revised version of VAX Text Processing Utility Manual for
more detailed information.
o New /INTERFACE Qualifier
This qualifer, which you use to specify either character-cell or
DECwindows interface, has been added for compatibility with
other DECwindows applications. It is essentially the same as the
/DISPLAY qualifier.
o New GET_INFO Built-In Procedures
New GET_INFO built-in procedures enable you to determine the
following:
- Widget input focus
- Keystroke journal recovery
- Work file name
- Key name
- Cursor position after vertical motion operations
- Scroll setting
- Automatic pop-up menu positioning
o MARK Built-In Procedure
An enhancement to the MARK built-in procedure enables you to
create markers at arbitrary positions within a buffer. Previously,
markers could be created only at the current editing point.
o SET (KEYSTROKE_RECOVERY) Built-In Procedure
This new built-in procedure turns keystroke journal recovery on
or off, regardless of whether such recovery was specified when
the VAXTPU session was started.
o SET (MENU_POSITION) Built-In Procedure
This new built-in procedure lets you set automatic pop-up menu
positioning for one or more pop-up widgets.
o SET (MOVE_VERTICAL_CONTEXT) Built-In Procedure
This new built-in procedure allows an application to restore the
column context value for a buffer.
o SET (SCROLLING) Built-In Procedure
An enhancement to the SET (SCROLLING) built-in procedure)
enables you to specify jump or smooth scrolling.
o WorkFile Support
The creation of work files enables VAXTPU to handle files larger
than the available virtual memory, thus significantly increasing
the size of files that you can edit.
VMSINSTAL
VMSINSTAL provides a new parameter and three new and enhanced
callbacks.
o New Parameter for SPKITBLD.COM Procedure
The Software Product Kit Building Command Procedure
(SPKITBLD.COM) now has an additional parameter, the data-file
parameter (P4). You use this parameter to specify the name of a
data file; SPKITBLD.COM uses the data file to obtain information
that it needs to perform a product kit build. For more
information on the SPKITBLD.COM data-file parameter, see the VMS
Developer's Guide to VMSINSTAL
New and Enhanced VMSINSTAL Callbacks.
o CHECK_VMS_VERSION VMSINSTAL Callback
The VMSINSTAL callback CHECK_VMS_VERSION has a new valid value
for the option parameter (P4), the value S. When you specify S
for the option parameter, messages are not output to the screen
during product installation. For more information on the CHECK_
VMS_VERSION callback, see the VMS Developer's Guide to
VMSINSTAL.
o New Option for SET VMSINSTAL Callback
The VMSINSTAL callback SET has a new option, SET SHUTDOWN. The
SET SHUTDOWN option specifies that a reboot is necessary in
order to complete the product installation. For a description of
the SET SHUTDOWN option, see the VMS Developer's Guide to
VMSINSTAL.
o GET_PASSWORD VMSINSTAL Callback
A new VMSINSTAL callback, GET_PASSWORD, obtains a
system-generated or installer-specified password. For more
information about the GET_PASSWORD callback, see the VMS
Developer's Guide to VMSINSTAL.
DECwindows and CDA Programming Features
Version 5.4 of the VMS operating system includes the following new
DECwindows and CDA programming features:
o New DECwindows programming examples
o Enhancements to the XUI Toolkit color mixing widget
o Display PostScript support
o PostScript support for the CDA VIEW command, CDA Viewer support
of Adobe font metrics and DECmath fonts, and the availability
of new CDA documentation.
Display PostScript and PostScript are registered trademarks of
Adobe Systems Incorporated.
Additional information available:
New Programming Examples in DECW$EXAMPLES DirectoryXUI Toolkit Color Mixing Widget Enhancement
VMS DECwindows Display PostScript SystemCompound Document Architecture (CDA) Features
New Programming Examples in DECW$EXAMPLES Directory
The DECW$EXAMPLES directory has four new programming examples: o BTrap o TestVHist o TestVList o VDragExample
Additional information available:
BTrap-Broadcast Message TrapperTestVHist-Histogram Widget ExerciserTestVList-VList Widget Exerciser
VDragExample-VDrag Exerciser
BTrap-Broadcast Message Trapper
BTrap (Broadcast Message Trapper) is a program that traps
broadcast messages and displays them in a scrollable output
window. The example program shows how to do the following:
o Use XtAddInput to make AST completion routines compatible with
the DECwindows toolkit
o Implement pop-up menus
o Implement a custom widget (the TList widget)
o Save current geometry settings in a resource file, under
program control
The BTrap package consists of the following files:
o BTrap.c - Main module for the sample program
o BTrap.uil - UIL file for the sample program
o TList.c - TList widget sources
o TList.h - TList widget include file
o TList.note - TList widget documentation
o TList.uil - TList widget UIL include file
TestVHist-Histogram Widget Exerciser
The TestVHist (Histogram Widget Exerciser) program exercises the VHist widget, a dynamically updatable bar histogram widget. It shows how to include a VHist widget in an application program. The TestVHist package consists of the following files: o TestVHist.c - Main module for the sample program o TestVHist.uil - UIL file for the sample program o VHist.c - VHist widget sources o VHist.h - VHist widget include file o VHist.note - VHist widget documentation o VHist.uil - VHist widget UIL include file
TestVList-VList Widget Exerciser
The TestVList (VList widget exerciser) program exercises the VList widget, a dynamic, customizable list box widget. It shows how to include a VList widget in an application program. The TestVList package consists of the following files: o TestVList.c - Main module for the sample program o TestVList.uil - UIL file for the sample program o VList.c - VList widget sources o VList.h - VList widget include file o VList.note - VList widget documentation o VList.uil - VList widget UIL include file o VFrame.c - VFrame widget sources o VFrame.h - VFrame widget include file o VFrame.uil - VFrame widget UIL include file o VHeader.c - VHeader widget sources o VHeader.h - VHeader widget include file o VHeader.uil - VHeader widget UIL include file
VDragExample-VDrag Exerciser
The VDragExample (VDrag Exerciser) program exercises the VDrag routine, which allows the user to drag widgets about within a window. It shows how to intercept button and motion events to move a widget while tracking the pointer. The VDragExample package consists of these files: o VDragExample.c - Main module for the sample program o VDrag.c - VDrag routine sources o VDrag.note - VDrag routine documentation
XUI Toolkit Color Mixing Widget Enhancement
The XUI Toolkit color mixing widget, created by the COLOR MIX
CREATE routine, now supports both the Hue Lightness Saturation
(HLS) color model as well as the Red, Green, Blue (RGB) model. The
HLS color model allows users to choose the hue (color), lightness
of the color, and the color saturation, which determines how
solidly the color appears. The RGB color model provides three
scales, each of which represents a percentage of red, green, and
blue.
The same X11 RGB callback information is returned regardless of
which color model is used. An option menu presents the HLS and RGB
color model choices and allows users to switch between models as
often as they wish.
The COLOR MIX CREATE routine includes eleven new attributes that
support the HLS model:
o color_model - The color model currently being used.
o hue_label - The label of the hue scale widget.
o light_label - The label of the lightness scale widget.
o sat_label - The label of the saturation scale widget.
o black_label - The label for the zero end of lightness scale
widget.
o white_label - The label for the 100% end of lightness scale
widget.
o gray_label - The label for the zero end of saturation scale
widget.
o full_label - The label for the 100% end of the saturation scale
widget.
o option_label - The label for the color model option menu.
o hls_label - The label for the color model option menu HLS
option.
o rgb_label - The label for the color model option menu RGB
option.
See the VMS DECwindows Toolkit Routines Reference Manual for a
complete description of the COLOR MIX CREATE routine.
VMS DECwindows Display PostScript System
VMS Version 5.4 includes the Display PostScript system by
Adobe Systems Incorporated (Adobe Systems), which provides
text and image display capability for bitmapped workstations.
The DECwindows implementation of the Display PostScript system
allows programmers to write applications in a general purpose
language like C, yet describe the images and text using the
device-independent PostScript software. Programmers can mix X
and PostScript routines, even within a single window, using a
single network connection to an X server.
The Display PostScript system provides additional imaging
capabilities to the X programming routines, as follows:
o Coordinate system that can be moved, rotated, and scaled
o Bezier curves to make it easy to display any curve, no matter
how complex
o Device-independent color model
o Text that can be scaled and rotated
o Image operators for scanned images (scaling, rotating,
transformations, gray-scale manipulation)
The Display PostScript system is a device-independent graphics
architecture that can be implemented on a variety of windowing
systems. The Display PostScript server consists mainly of a
PostScript interpreter, which executes PostScript language code to
display images on a user's screen. The Display PostScript client
consists mainly of a Client Library, through which an application
communicates with the server.
DECwindows implements the Display PostScript system as an
extension to the X Window System, on which DECwindows is based.
The Display PostScript server is an extension to the X server;
the Client Library is an extension to Xlib. The Display PostScript
extensions allows an application written in any VAX language to
handle Display PostScript programming tasks on an X-based system.
Compound Document Architecture (CDA) Features
For VMS Version 5.4 of the operating system, CDA includes
PostScript support for the VIEW command, CDA Viewer support of
Adobe font metrics and DECmath fonts, and the availability of
new CDA documentation.
Additional information available:
PostScript Support for CDA VIEW Command:CDA Viewer Support of Adobe Font Metrics
New CDA Documentation
PostScript Support for CDA VIEW Command:
The VMS VIEW command invokes the CDA Viewer, which lets you view a compound document file on a character cell terminal or DECwindows display. With the Version 5.4 release of the VMS operating system, PS is now a supported input format (.PS file extension). Note that PostScript file viewing is supported only in the DECwindows CDA Viewer and only when running to displays with servers containing the Display PostScript Extension. To view a PostScript file, you must specify the /INTERFACE=DECWINDOWS qualifier. PostScript file viewing does not support processing options. For more information about the VIEW command, see the CDA Reference Manual.
CDA Viewer Support of Adobe Font Metrics
The CDA Viewer now uses the Adobe font metrics in processing a DDIF file for viewing. The font name in a DDIF file follows the X- 11 font naming convention. When processing a file from a creating application that uses font metrics other than Adobe font metrics, the CDA Viewer defaults to the Adobe Courier font. When processing a file for viewing, the DECwindows CDA Viewer queries the X server for a list of available fonts Although the CDA Viewer does not use these fonts in its calculations, it tries to match the font from the file with an X11 font on the server. If there is not an exact match, the CDA Viewer uses the font from the list that is the closest lower point size for that font name. If there is no match at all, the DECwindows CDA Viewer display type defaults to 12 point Adobe Courier. The character cell CDA Viewer displays all files in a 12 point Courier font. The contents of each file are spaced and displayed correctly, based on the font that is stored in the file. The Adobe font metrics are stored in SYS$PS_FONT_METRICS:.AFM on VMS systems and in /usr/lib/font/metrics/ on ULTRIX systems. The CDA Viewer also supports the DECmath fonts used by DECwrite for equation editing. For more information, see the CDA Reference Manual.
New CDA Documentation
The following separately orderable manuals are now available:
o The Introduction to the CDA Services provides an overview of
compound document processing terminology and the various
components of CDA, which include the CDA Toolkit, the CDA
converter architecture, DDIF, and DTIF.
o The Guide to Creating Compound Documents with the CDA Toolkit
is a tutorial manual that describes how to use the CDA Toolkit
to create CDA-conforming compound document applications on VMS
and on ULTRIX systems.
o The the CDA Reference Manualprovides reference material
that supplements the CDA user guides. It describes the
DDIF and DTIF aggregates, the CDA Toolkit routines, the front
and back end converter routines, the callable DECwindows and
character-cell viewer routines, and the VMS and ULTRIX system
commands used to convert and to view compound document files.
See the Overview of the VMS Documentation for more information
about these manuals.