Transportation Administration System
Snoezelen Pillows for Dementia
Begeleiders voor gehandicapten
Laat uw hond het jaarlijkse vuurwerk overwinnen
Betuweroute en Kunst
Hey Vos! Je eigen naam@vos.net emailadres?
Kunst in huis? Nicole Karrèr maakt echt bijzonder mooie dingen
Kunst in huis? Netty Franssen maakt ook bijzonder mooie dingen1 Lexicals
A set of functions that return information about character strings and attributes of the current process. 2 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 an OpenVMS Cluster system. Format F$CONTEXT(context-type, context-symbol, selection-item, selection-value, value-qualifier) 3 Return_Value A null string (""). 3 Arguments 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 criterion to use. Use only one selection-item keyword per call to F$CONTEXT. NOTE Do not use the NEQ selection value on a list of items because it causes the condition to always be true. For example: $ EXAMPLE=f$context("PROCESS",CTX,"USERNAME","A*,B*","NEQ") This equation is parsed as "if the user name is not equal to A* or the user name is not equal to B*, then return the process of the users that meet the criteria." Because the operand is a logical or, the conditions will always be true (any name will be found to be not equal to A* or B*; ALFRED will not be equal to B*; BOB will not be equal to A*). The following table shows valid selection-item keywords for the PROCESS context type: Selection Selection Value Item Value Qualifiers Comments ACCOUNT String EQL, NEQ Valid account name or list of names. The asterisk (*) and the percent sign (%) wildcard characters are allowed. AUTHPRI Integer GEQ, On Alpha, valid authorized base GTR, priority (0-63). On VAX, valid LEQ, authorized base priority (0-31). LSS, EQL, NEQ CANCEL Cancels the selection criteria for this context. CURPRIV Keyword ALL, Valid privilege name keyword ANY, or list of keywords. For more EQL, NEQ information, see the OpenVMS Guide to System Security. GRP Integer GEQ, UIC group number. GTR, 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. The asterisk (*) and the percent sign (%) wildcard characters are allowed. JOBPRCCNT Integer GEQ, Subprocess count for entire job. GTR, 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 OpenVMS User's Manual. MASTER_ String EQL, NEQ PID of master process. PID MEM Integer GEQ, UIC member number. GTR, LEQ, LSS, EQL, NEQ MODE Keyword EQL, NEQ Valid process mode keyword. Valid keywords are OTHER, NETWORK, BATCH, and INTERACTIVE. For more information, see the OpenVMS User's Manual. NODE_ Integer EQL, NEQ Node's cluster ID number. CSID NODENAME String EQL, NEQ Node name or list of node names. The asterisk (*) and the percent sign (%) 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, Subprocess count of process. GTR, LEQ, LSS, EQL, NEQ PRCNAM String EQL, NEQ Process name or list of process names. The asterisk (*) and the percent sign (%) wildcard characters are allowed. PRI Integer GEQ, Process priority level number GTR, (0-63, on Alpha), (0-31, on VAX). LEQ, LSS, EQL, NEQ PRIB Integer GEQ, Base process priority level number GTR, (0-63, on Alpha), (0-31, on VAX). LEQ, LSS, EQL, NEQ STATE Keyword EQL, NEQ Valid process state keyword. For more information, see the description of the $GETJPI service in the OpenVMS System Services Reference Manual. STS Keyword EQL, NEQ Valid process status keyword. For more information, see the description of the $GETJPI service in the OpenVMS System Services Reference Manual. TERMINAL String EQL, NEQ Terminal name or list of names. The asterisk (*) and the percent sign (%) 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. The asterisk (*) and the percent sign (%) wildcard characters 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 the asterisk (*) and the percent sign (%) wildcard characters 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 one of the following process values: o LSS - less than the value specified in the call to F$PID o LEQ - less than or equal to the value specified in the call to F$PID o GTR - greater than the value specified in the call to F$PID o GEQ - greater than or equal to the value specified in the call to F$PID o EQL - equal to the value specified in the call to F$PID o NEQ - not equal to 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. o ALL - requires that all items in the list be true for a process o ANY - requests that any item in the list be part of the attributes of a process o EQL - requires the values to match exactly (that is, values not specified must not be true of the process) o NEQ - requires that the value must not match When using multiple selection values with a particular selection qualifier, a match on any one of the selection criteria is considered valid (as if an OR operand was in place); the selection values are not cumulative criteria (as if an AND operand was in place). 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. 3 Examples 1.$!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 was used with F$PID until an error occurred or until the end of the process list was reached. 2.f$context("process",ctx,"prcnam ","symbiont*,mcote*","eql") f$context("process",ctx,"prcnam ","symbiont*,mcote* ","neq") f$context("process",ctx,"prcnam ","mcote* ","neq") f$context("process",ctx,"prcnam ","symbiont*","neq") This example shows three sets of lexicals showing the difference between the EQL and the NEQ selection values. The first lexical function (with EQL) passes back all processes with symbiont and mcote in the process name. The second and third lexical functions (with NEQ) are equivalent in that they both will pass back all processes (processes that do not have symbiont in the process name, or processes that do not have mcote in the process name.) 2 F$CSID Returns an identification number from an OpenVMS Cluster system and updates the context symbol to point to the current position in the system's cluster node list. Format F$CSID(context-symbol) 3 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 cluster identification number is returned, the F$CSID function returns a null string (""). 3 Arguments 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 identification number. 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 cluster identification number of the first system in the system's cluster node list. Subsequent calls to the F$CSID function will return the cluster identification number of the rest of the nodes in the cluster. 3 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 either is 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. 2 F$CVSI Converts the specified bits in the specified character string to a signed number. Format F$CVSI(start-bit,number-of-bits,string) 3 Return_Value The integer equivalent of the extracted bit field, converted as a signed value. 3 Arguments 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. 3 Examples 1.$ 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. 2.$ SYM[0,32] = %X2A $ SHOW SYMBOL SYM SYM = "*..." $ Y = F$CVSI(0,33,SYM) %DCL-W-INVRANGE, field specification is out of bounds - check sign and size $ SHOW SYMBOL Y %DCL-W-UNDSYM, undefined symbol - check spelling In this example, the width argument specified with the F$CVSI function is too large. Therefore, DCL issues an error message and the symbol Y is not assigned a value. 2 F$CVTIME Converts 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 absolute, combination, or delta time string. Format F$CVTIME([input_time] [,output_time_format] [,output_field]) 3 Return_Value A character string containing the requested information. 3 Arguments input_time Specifies a string containing absolute, a delta, or a combination 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 specifying time values, see the OpenVMS User's Manual or the topic SPECIFY Date_Time in online help. 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. Single-digit days are returned with no leading space or zero. 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. 3 Examples 1.$ TIME = F$TIME() $ SHOW SYMBOL TIME TIME = "14-DEC-1994 10:56:23.10" $ TIME = F$CVTIME(TIME) $ SHOW SYMBOL TIME TIME = "1994-12-14 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_ format argument that is omitted. 2 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) 3 Return_Value The integer equivalent of the extracted bit field, converted as an unsigned value. 3 Arguments 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. 3 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. 2 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]) 3 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 (""). 3 Arguments search_devnam Specifies the name of the device for which F$DEVICE is to search. The asterisk (*) and the percent sign (%) wildcard characters are allowed in the search_devnam argument. Specify the search_devnam argument as a character string expression. devclass Specifies 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. Value Device Class Device Name 1 Disk device DISK 2 Tape device TAPE 32 Synchronous SCOM communications device 65 Card reader CARD 66 Terminal TERM 67 Line printer LP 70 Workstation WORKSTATION 96 Real-time REALTIME 97 DECvoice DECVOICE 128 Bus BUS 160 Mailbox MAILBOX 170 Remote console REMCSL_STORAGE storage 200 Miscellaneous device MISC devtype Specifies 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. Valid type names can be found under F$GETDVI. 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 use 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. 3 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. 2 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() 3 Return_Value A character string for the current default directory name, including 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. 3 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. 2 F$EDIT Edits the character string based on the edits specified in the edit-list argument. Format F$EDIT(string, edit-list) 3 Return_Value A character string containing the specified edits. 3 Arguments 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: 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. If you specify more than one keyword, separate them with commas (,). Do not abbreviate these keywords. 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. NOTE When UPCASE is specified with LOWERCASE in an edit-list, UPCASE takes precedence. 3 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. 3.$ UNCOMMENT_LINE = F$EDIT("$ DIR ! THIS IS THE COMMENT", "UNCOMMENT") $ SHOW SYMBOL UNCOMMENT_LINE $ UNCOMMENT_LINE = "$ DIR" This example uses the F$EDIT function to remove comments. 2 F$ELEMENT Extracts one element from a string of elements. Format F$ELEMENT(element-number, delimiter, string) 3 Return_Value A character string containing the specified element. 3 Arguments 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. 3 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 "1". The procedure runs the index, chapter 2. Processing continues until the result of the F$ELEMENT call is the delimiter specified in the call. 2 F$ENVIRONMENT Returns information about the current DCL command environment. Format F$ENVIRONMENT(item) 3 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. 3 Argument item Specifies the type of information to be returned. Specify one of the following keywords (do not abbreviate these keywords): Data Item Type Information Returned CAPTIVE String TRUE if you are logged in to a captive account. The system manager can define captive accounts in the user authorization file (UAF) by using the Authorize utility (AUTHORIZE). CONTROL String Control characters currently enabled with SET CONTROL. Multiple characters are separated by commas; if no control characters are enabled, the null string ("") is returned. DEFAULT String Current default device and directory name. The returned string is the same as SHOW DEFAULT output. DEPTH Integer Current command procedure depth. The command procedure depth is 0 when you log in interactively and when you submit a batch job. The command procedure depth is 1 when you execute a command procedure interactively or from within a batch job. A nested command procedure has a depth of 1 greater than the depth of the command procedure from which the nested procedure is executed. DISIMAGE String TRUE if you are logged in to an account that does not allow the use of the RUN and MCR commands or foreign commands. The system manager can add or remove the DISIMAGE attribute for accounts in the UAF by using AUTHORIZE. INTERACTIVE String TRUE if the process is executing interactively. KEY_STATE String Current locked keypad state. See the description of the DEFINE/KEY command for more information on keypad states. MAX_DEPTH Integer Maximum allowable command procedure depth. MESSAGE String Current setting of SET MESSAGE qualifiers. Each qualifier in the string is prefaced by a slash (/); therefore, the output from F$ENVIRONMENT("MESSAGE") can be appended to the SET MESSAGE command to form a valid DCL command line. NOCONTROL String Control characters currently disabled with SET NOCONTROL. Multiple characters are separated by commas (,); if no control characters are disabled, the null string is returned. ON_CONTROL_Y String If issued from a command procedure, returns TRUE if ON_CONTROL_Y is set. ON_ CONTROL_Y always returns FALSE at DCL command level. ON_SEVERITY String If issued from a command procedure, returns the severity level at which the action specified with the ON command is performed. ON_SEVERITY returns NONE when SET NOON is in effect or at DCL command level. OUTPUT_RATE String Delta time string containing the default output rate, which indicates how often data is written to the batch job log file while the batch job is executing. OUTPUT_RATE returns a null string if used interactively. PROCEDURE String File specification of the current command procedure. If used interactively, the terminal device name is returned. PROMPT String Current DCL prompt. PROMPT_ String TRUE if a carriage return and line feed CONTROL 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 in to 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 symbol scoping state for verbs. (For more information, see the description of the SET SYMBOL command.) 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_ String Returns the prefix control string set by PREFIX means of the SET PREFIX command. VERIFY_ String TRUE if procedure verification PROCEDURE SET VERIFY=PROCEDURE is in effect. If command verification is in effect, then the command procedure echoes DCL command lines. 3 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. 2 F$EXTRACT Extracts the specified characters from the specified string. Format F$EXTRACT(start,length,string) 3 Return_Value A character string containing the characters delimited by the start and length arguments. 3 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. 3 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. 2 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[,...]]) 3 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. 3 Arguments 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. 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.) 3 Directives Specify an FAO directive using any one of the following formats: Format Function !DD One directive !n(DD) A directive repeated a specified number of times !lengthDD A directive that places its output in a field of a specified length !n(lengthDD) A directive that is repeated a specified number of times and generates output fields of a specified length The exclamation point (!) indicates that the following character or characters are to be interpreted as an FAO directive. DD represents a 1- or 2-character uppercase code indicating the action that F$FAO is to perform. When specifying repeat counts, n is a decimal value specifying the number of times the directive is to be repeated. The length value is a decimal number that instructs F$FAO to generate an output field of "length" characters. Repeat counts and output lengths may also be specified by using a number sign (#) in place of absolute numeric value. If you use a number sign, you must specify the numeric value as an integer expression in the corresponding place in the argument list. When a variable output field is specified with a repeat count, only one length parameter is required, because each output string has the specified length. Here is a summary of the FAO directives you can specify in a control string. NOTE Two types of directives that are supported by the $FAO system service are not supported by the DCL F$FAO lexical function. These types are: o Quadword numeric directives, which are not supported in DCL because all DCL numeric values are stored and manipulated as longwords. o String directives other than the !AS directive, which are not supported in DCL because all DCL strings are stored and manipulated by descriptor. For further information on the $FAO system service directive, see the OpenVMS System Services Reference Manual. Argument Directive 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 Inserts the current time. equal to 0 !%D Integer Inserts the current date/time. equal to 0 Argument interpretation: !- None Reuses the last argument. !+ None Skips the next argument. 3 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 !-!0UL!1%Cchild!%Echildren!%F here",1) $ 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. 2 F$FILE_ATTRIBUTES Returns attribute information for a specified file. Format F$FILE_ATTRIBUTES(filespec,item) 3 Return_Value Either an integer or a character string, depending on the item you request. 3 Arguments 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 OpenVMS RMS field names listed in the following table. Return Item Type Information Returned AI String TRUE if after-image (AI) journaling is enabled; FALSE if disabled ALQ Integer Allocation quantity BDT String Backup date/time BI String TRUE if before-image (BI) journaling is enabled; FALSE if disabled BKS Integer Bucket size BLS Integer Block size CBT String TRUE if contiguous-best-try; otherwise FALSE CDT String Creation date/time CTG String TRUE if contiguous; otherwise 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; otherwise 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_ String TRUE if the file is a journal; otherwise FILE FALSE KNOWN String Known file; returns TRUE or FALSE to indicate whether file is installed with the Install utility (INSTALL). However, returns NOSUCHFILE if a file does not exist (for example, the file has been installed but subsequently deleted). LOCKED String TRUE if a file is deaccessed-locked; otherwise FALSE LRL Integer Longest record length MBM Integer Owner member number MOVE String TRUE if movefile operations are enabled; otherwise FALSE 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; otherwise 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 SHELVABLE String TRUE if the file is shelvable; otherwise FALSE SHELVED String TRUE if the file is shelved; otherwise FALSE STORED_ String ASCII string that represents stored SEMANTICS semantics UIC String Owner user identification code (UIC) string WCK String TRUE if write check; otherwise FALSE 3 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. 2 F$GETDVI Returns a specified item of information for a specified device. Format F$GETDVI(device-name,item) 3 Return_Value Either an integer or a character string, depending on the item you request. 3 Arguments 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 can 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 DEVICE_TYPE_NAME 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_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_CHARSET TT_CRFILL TT_CS_KANA TT_CS_KANJI TT_CS_HANZI TT_CS_HANGUL TT_CS_HANYU TT_CS_THAI 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 VPROT WCK 3 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. 2 F$GETJPI Returns information about 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) 3 Return_Value Either an integer or a character string, depending on the item you request. 3 Arguments 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 an asterisk (*) or percent sign (%) wildcard character 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 NODENAME NODE_CSID NODE_VERSION OWNER PAGEFLTS PAGFILCNT PAGFILLOC PGFLQUOTA PHDFLAGS PID PPGCNT PRCCNT PRCLM PRCNAM PRI PRIB PROC_INDEX PROCESS_RIGHTS PROCPRIV RIGHTSLIST RIGHTS_SIZE SHRFILLM SITESPEC SLOW_VP_SWITCH STATE STS SWPFILLOC SYSTEM_RIGHTS TABLENAME TERMINAL TMBU TQCNT TQLM TT_ACCPORNAM TT_PHYDEVNAM UAF_FLAGS UIC USERNAME VIRTPEAK VOLUMES VP_CONSUMER VP_CPUTIM WSAUTH WSAUTHEXT WSEXTENT WSPEAK WSQUOTA WSSIZE 3 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. 2 F$GETQUI Returns information about queues, including batch and print jobs currently in the queues, form definitions, and characteristic definitions kept in the queue database. Also returns information about queue managers. For most operations, read (R) access is required. Format F$GETQUI(function,[item],[object-id],[flags]) 3 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 (""). 3 Arguments 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. The following table lists these functions: Function Description CANCEL_OPERATION Terminates any wildcard operation that may have been initiated by a previous call to F$GETQUI. DISPLAY_ Returns information about a specific CHARACTERISTIC 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. Only those entries that match the user-name of the current process will be processed. 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_MANAGER Returns information about a specific queue manager or the next queue manager in a wildcard operation. 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_ F$GETQUI("CANCEL_OPERATION") or F$GETQUI(" ") OPERATION DISPLAY_ F$GETQUI("DISPLAY_CHARACTERISTIC", 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_MANAGER F$GETQUI("DISPLAY_MANAGER",[item], object- id,[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. On VAX, queue manager information is also available. These are the item codes: ACCOUNT_NAME AFTER_TIME ASSIGNED_QUEUE_NAME AUTOSTART_ON 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_COUNT 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_COMPLETION_QUEUE JOB_COMPLETION_TIME JOB_COPIES JOB_COPIES_DONE JOB_CPU_LIMIT JOB_ERROR_RETENTION 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_RETENTION JOB_RETENTION_TIME JOB_SIZE JOB_SIZE_MAXIMUM JOB_SIZE_MINIMUM JOB_STALLED JOB_STARTING JOB_STATUS JOB_SUSPENDED JOB_TIMED_RELEASE JOB_WSDEFAULT JOB_WSEXTENT JOB_WSQUOTA LAST_PAGE LIBRARY_SPECIFICATION LOG_QUEUE LOG_SPECIFICATION MANAGER_NAME MANAGER_NODE MANAGER_STATUS NOTE OPERATOR_REQUEST OWNER_UIC PAGE_SETUP_MODULES PARAMETER_1 to PARAMETER_8 ENDING_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_AUTOSTART QUEUE_AUTOSTART_INACTIVE QUEUE_AVAILABLE QUEUE_BATCH QUEUE_BUSY QUEUE_CLOSED QUEUE_CPU_DEFAULT QUEUE_CPU_LIMIT QUEUE_DESCRIPTION QUEUE_DIRECTORY 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_STOP_PENDING 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 SECURITY_INACCESSIBLE SUBMISSION_TIME TIMED_RELEASE_JOB_COUNT UIC USERNAME WSDEFAULT WSEXTENT WSQUOTA object-id Corresponds to the $GETQUI system service QUI$SEARCH_NAME, QUI$_ SEARCH_NUMBER, and QUI$_SEARCH_JOB_NAME input item codes. The object-id argument specifies either the name or the number of an object (for example, a specific queue name, job name, or form number) about which F$GETQUI is to return information. The asterisk (*) and the percent sign (%) wildcard characters are allowed for the following functions: DISPLAY_CHARACTERISTIC DISPLAY_ENTRY DISPLAY_FORM DISPLAY_MANAGER DISPLAY_QUEUE By specifying an asterisk (*) or percent sign (%) wildcard character 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 name is used with wildcard characters, 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 keywords in the following table can be used only with certain function codes. Valid Function Keyword 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 wildcard DISPLAY_ENTRY context to the next object. DISPLAY_FILE If you do not specify DISPLAY_FORM this flag, the context is DISPLAY_JOB advanced to the next object. DISPLAY_MANAGER DISPLAY_QUEUE GENERIC DISPLAY_ENTRY Selects generic queues for DISPLAY_QUEUE 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 retained. DISPLAY_JOB SERVER DISPLAY_QUEUE Selects server queues. DISPLAY_ENTRY SYMBIONT DISPLAY_QUEUE Selects all output queues. DISPLAY_ENTRY Equivalent to specifying "PRINTER,SERVER,TERMINAL". TERMINAL DISPLAY_QUEUE Selects terminal queues. DISPLAY_ENTRY THIS_JOB DISPLAY_FILE Selects all job file DISPLAY_JOB information about the DISPLAY_QUEUE calling batch job, the command file being executed, or the queue associated with the calling batch job. TIMED_RELEASE_ DISPLAY_ENTRY Selects jobs on hold until a JOBS DISPLAY_JOB specified time. WILDCARD DISPLAY_ Establishes and saves a CHARACTERISTIC context. Because the context DISPLAY_ENTRY is saved, the next operation DISPLAY_FORM can be performed based on DISPLAY_MANAGER that context. DISPLAY_QUEUE 3 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") $ WRITE SYS$OUTPUT " JOB: ", JNAME $ GOTO JLOOP This sample command procedure displays all the queues in the system and all the jobs to which the user has read access 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. 4.$ THIS_NODE = F$EDIT(F$GETSYI("SCSNODE"),"COLLAPSE") $ TEMP = F$GETQUI("CANCEL_OPERATION") $ SET NOON $LOOP: $ QUEUE = F$GETQUI("DISPLAY_QUEUE","QUEUE_NAME","*","WILDCARD") $ IF QUEUE .EQS. "" THEN GOTO ENDLOOP $ IF THIS_NODE .EQS.- F$GETQUI("DISPLAY_QUEUE","SCSNODE_NAME","*","WILDCARD,FREEZE_CONTEXT") $ THEN $ IF .NOT.- F$GETQUI("DISPLAY_QUEUE","QUEUE_AUTOSTART","*","WILDCARD,FREEZE_CONTEXT")- THEN START/QUEUE 'QUEUE' $ ENDIF $ GOTO LOOP $ENDLOOP: $ SET ON This command procedure looks at all queues associated with the local cluster node and starts any queue that is not marked as autostart. The procedure starts by obtaining the nodename of the local system and clearing the F$GETQUI context. In addition, error handling is turned off for the loop so that, if a queue had been started previously, the resulting error from the START QUEUE command does not abort the command procedure. Inside the loop, the F$GETQUI function gets the next queue name in the queue list. If the result is empty, then it has reached the end of the list and it exits the loop. The next IF statement checks to see if the queue runs on the local node. If it does, then the next statement checks to see if the queue is marked as an autostart queue. If that is false, then the queue is started with the start command. The loop is then repeated. The final command of the procedure restores DCL error handling to the previous setting. 2 F$GETSYI Returns status and identification information about the local system (or about a node in the local dual-architecture OpenVMS Cluster system, if your system is part of an OpenVMS Cluster). Format F$GETSYI(item [,node-name] [,cluster-id]) 3 Return_Value Either an integer or a character string, depending on the item you request. 3 Arguments item Indicates the type of information to be reported about the local node (or about another node in your OpenVMS Cluster, if your system is part of a OpenVMS Cluster). 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 ARCHFLAG ARCH_NAME ARCH_TYPE AVAILCPU_CNT BOOTTIME CHARACTER_EMULATED CONSOLE_VERSION* CONTIG_GBLPAGES CPU** CPU_TYPE* DECIMAL_EMULATED D_FLOAT_EMULATED ERRORLOGBUFFERS F_FLOAT_EMULATED FREE_GBLPAGES FREE_GBLSECTS G_FLOAT_EMULATED GH_RSRVPGCNT* ITB_ENTRIES* MEMSIZE PAGEFILE_FREE PAGEFILE_PAGE PALCODE_VERSION* QUANTUM SCS_EXISTS SID SWAPFILE_FREE SWAPFILE_PAGE SYSTEM_RIGHTS SYSTYPE* USED_GBLPAGCNT USED_GBLPAGMAX VERSION * Alpha specific ** VAX specific Here are the items you can specify to get information about either your local node, or another node in your OpenVMS Cluster system. If you do not specify the node argument, the information is returned for the local node. CLUSTER_EVOTES CLUSTER_FSYSID CLUSTER_FTIME CLUSTER_MEMBER CLUSTER_NODES CLUSTER_QUORUM CLUSTER_VOTES DECNET_FULLNAME HW_MODEL HW_NAME NODENAME NODE_AREA NODE_CSID NODE_EVOTES NODE_HWTYPE NODE_HWVERS NODE_NUMBER NODE_QUORUM NODE_SWINCARN NODE_SWTYPE NODE_SWVERS NODE_SYSTEMID NODE_VOTES REAL_CPUTYPE* VECTOR_EMULATOR VP_MASK VP_NUMBER * Alpha specific You can also specify any of the system parameters listed in the OpenVMS System Management Utilities Reference Manual. However, you can specify system parameters only for your local node; you cannot specify the node-name argument with these items. node-name Specifies the node in your OpenVMS Cluster system for which information is to be returned. Specify the node as a character string expression. You cannot use the asterisk (*) and the percent sign (%) wildcard characters to specify the node-name argument. (This argument can be specified only if your system is part of an OpenVMS Cluster.) 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 an OpenVMS Cluster.) 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. 3 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 cluster. The return value TRUE indicates that the remote node LONDON is a member of the cluster. 3.$ LIM = F$GETSYI("BJOBLIM") $ SHOW SYMBOL LIM LIM = 16 Hex = 00000010 Octal = 00000000020 This example uses the system parameter BJOBLIM as an argument for the F$GETSYI function. This argument returns the batch job limit for the current system. 2 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. The system uses identifiers to determine a user's access to a resource. Format F$IDENTIFIER(identifier,conversion-type) 3 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). 3 Arguments 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. Any identifier holding the Name Hidden attribute will cause the F$IDENTIFIER to return an error when you do not hold the identifier in question or do not have access to the rights database. For further information on the attribute, see the OpenVMS Guide to System Security. 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". 3 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. 2 F$INTEGER Returns the integer equivalent of the result of the specified expression. Format F$INTEGER(expression) 3 Return_Value An integer value that is equivalent to the specified expression. 3 Argument 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. 3 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. 2 F$LENGTH Returns the length of the specified character string. Format F$LENGTH(string) 3 Return_Value An integer value for the length of the string. 3 Argument string Specifies the character string whose length is being determined. Specify the string argument as a character string expression. 3 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. 2 F$LOCATE Locates a specified portion of a character string and returns as an integer the offset of the first character. (An offset is the position of a character or a substring relative to the begining of the string. The first character in a string is always offset position 0 from the beginning of the string.) 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) 3 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.) 3 Arguments 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. 3 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. 2 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[,message-component-list]) 3 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 OpenVMS System Messages: Companion Guide for Help Message Users. 3 Arguments status-code Specifies the status code for which you are requesting error message text. You must specify the status code as an integer expression. message-component-list Specifies the system message component for which information is to be returned. If this parameter is null or unspecified, then all system message components are returned. The following table describes the valid system message component keywords: Component Keyword Information returned FACILITY Facility name SEVERITY Severity level indicator IDENT Abbreviation of message text TEXT Explanation of message Note that when the FACILITY, SEVERITY, and IDENT code keywords are specified (individually or in combination), the resulting message code is prefaced with the percent (%) character. The individual parts of the message code are separated by hyphens when multiple code keywords are specified. When only the TEXT keyword is specified, the resulting text is not prefaced with any character. When the TEXT keyword is specified with the FACILITY, SEVERITY, or IDENT code keyword, the message code is separated from the text by a combination of a comma and a blank (, ). 3 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. $ SUBMIT IMPORTANT.COM $ SYNCHRONIZE /entry='$ENTRY' $ IF $STATUS THEN EXIT $! $ JOB_STATUS = $STATUS $! $ IF "%JOBDELETE" .EQS. F$MESSAGE (JOB_STATUS, "IDENT") $ THEN . . . $ ELSE $ IF "%JOBABORT" .EQS. F$MESSAGE (JOB_STATUS, "IDENT") $ THEN . . . $ ELSE $ . . . $ ENDIF $ ENDIF . . . This command procedure submits a batch job and waits for it to complete. Upon successful completion, the procedure exits. If the job completes unsuccessfully, more processing is done based on the termination status of the batch job. The first command submits the command procedure IMPORTANT.COM. In the second command, the SYNCHRONIZE command tells the procedure to wait for the job to finish. The third command determines if the job completed successfully and, if so, the procedure exits. The next command saves the status in a symbol. The first IF statement uses F$MESSAGE to determine whether the job was deleted before execution. If so, it does some processing, possibly to resubmit the job or to inform a user via MAIL. The next IF statement uses F$MESSAGE to determine whether the job was deleted during execution. As a result, some cleanup or human intervention may be required, which would be done in the THEN block. If neither IF statement was true, then some other unsuccessful status was returned. Other processing, which would be done in the block following the ELSE statement, might be required. 2 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() 3 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. 3 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. 2 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]) 3 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. In most cases, the F$PARSE function returns a null string ("") if an error is detected during the parse. For example, a null string is returned if the file specification has incorrect syntax or if a disk or directory does not exist, making the file specification logically incorrect. However, when you specify a field name or the SYNTAX_ONLY parse type, F$PARSE returns the appropriate information. 3 Arguments filespec Specifies a character string containing the file specification to be parsed. The file specification can contain the asterisk (*) and the percent sign (%) wildcard characters. 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_ The syntax of the file specification is checked ONLY without verifying that the specified directory exists on the specified device. 3 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 [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. 2 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) 3 Return_Value A character string containing the PID of a process in the system's list of processes. 3 Argument 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 privilege, 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 processes that meet the selection criteria set up by the F$CONTEXT function and that are accessible to your current privileges. 3 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. 2 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) 3 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. 3 Arguments 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 OpenVMS Guide to System Security. Specify any one of the process privileges except [NO]ALL. 3 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, GROUP, and TMPMBX privileges and if you do not have 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. 2 F$PROCESS Obtains the current process name string. The F$PROCESS function has no arguments, but must be followed by parentheses. Format F$PROCESS() 3 Return_Value A character string containing the current process name. 3 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. 2 F$SEARCH Searches a directory file and returns the full file specification for a file you specify. Format F$SEARCH(filespec[,stream-id]) 3 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 (""). 3 Arguments 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 the asterisk (*) or the percent sign (%) wildcard characters, 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 starts searching at the beginning of the directory file each time you specify a different filespec argument. 3 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 an asterisk (*) wildcard character is not used as the version number.) The filespec argument SYS$SYSTEM:*.EXE is surrounded by 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 .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 .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 .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. 2 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 OpenVMS System Services Reference Manual. Format F$SETPRV(priv-states) 3 Return_Value A character string containing keywords for the current process privileges before they were changed by the F$SETPRV function. 3 Argument 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 OpenVMS User's Manual. 3 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 14-DEC-1994 15:55:09.60 RTA1: User: SMITH 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 14-DEC-1994 10:21:18.32 User: METCALFE Process ID: 00000F24 Node: TOKNOW Process name: "_FTA23:" Authorized privileges: NETMBX SETPRV SYSPRV TMPMBX Process privileges: ACNT may suppress accounting messages ALLSPOOL may allocate spooled device ALTPRI may set any priority value AUDIT may direct audit to system security audit log BUGCHK may make bug check log entries BYPASS may bypass all object access controls CMEXEC may change mode to exec CMKRNL may change mode to kernel DETACH may create detached processes DIAGNOSE may diagnose devices DOWNGRADE may downgrade object secrecy EXQUOTA may exceed disk quota GROUP may affect other processes in same group GRPNAM may insert in group logical name table GRPPRV may access group objects via system protection IMPORT may set classification for unlabeled object LOG_IO may do logical i/o MOUNT may execute mount acp function NETMBX may create network device OPER may perform operator functions PFNMAP may map to specific physical pages PHY_IO may do physical i/o PRMCEB may create permanent common event clusters PRMGBL may create permanent global sections PRMMBX may create permanent mailbox PSWAPM may change process swap mode READALL may read anything as the owner SECURITY may perform security administration functions SETPRV may set any privilege bit SHARE may assign channels to non-shared devices SHMEM may create/delete objects in shared memory SYSGBL may create system wide global sections SYSLCK may lock system wide resources SYSNAM may insert in system logical name table SYSPRV may access objects via system protection TMPMBX may create temporary mailbox UPGRADE may upgrade object integrity VOLPRO may override volume protection WORLD may affect other processes in the world Process rights: INTERACTIVE LOCAL System rights: SYS$NODE_TOKNOW $ NEWPRIVS = F$SETPRV(NEWPRIVS) $ SHOW PROCESS/PRIVILEGE 14-DEC-1994 16:05:07.23 RTA1: User: METCALFE 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. Entering 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. 4.$ SHOW PROCESS/PRIVILEGE 14-DEC-1994 15:55:09.60 RTA1: User: METCALFE Process privileges: AUDIT may direct audit to system security audit log DOWNGRADE may downgrade object secrecy IMPORT may set classification for unlabeled object UPDATE These process privileges are VAX specific and are used only in Security Enhancement Service Software (SEVMS) on an OpenVMS VAX system. 2 F$STRING Returns the string that is equivalent to the specified expression. Format F$STRING(expression) 3 Return_Value A character string equivalent to the specified expression. 3 Argument 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 zeros. When converting a negative integer, the F$STRING function places a minus sign at the beginning string representation of the integer. 3 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. 2 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() 3 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. 3 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. 2 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]) 3 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. 3 Arguments 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. A logical name for a logical name table must be defined in one of the following logical name tables: o LNM$SYSTEM_DIRECTORY o LNM$PROCESS_DIRECTORY NOTE If you subsequently create a table using the CREATE/NAME_ TABLE command and want to make your private table accessible for F$TRNLNM, you must redefine one of the table logical names to include your private table. To see all the tables that are normally searched by F$TRNLNM, issue the following command: $ SHOW LOGICAL/STRUCTURE LNM$DCL_LOGICAL For more information, see the CREATE/NAME_TABLE amd SHOW LOGICAL commands. 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_ String One of the following access modes associated MODE 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_ String Name of the table where the logical name was NAME 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. 3 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. 3.$ RESULT= - _$ F$TRNLNM("INFILE","LNM$PROCESS",0,"SUPERVISOR",,"NO_ALIAS") $ SHOW SYMBOL RESULT RESULT = "FALSE" In this example, the F$TRNLNM function searches the process logical name table for the logical name INFILE. The function starts the search by looking for the logical name INFILE created in supervisor mode. If no match is found, the function looks for INFILE created in executive mode. When a match is found, the F$TRNLNM function determines whether the name INFILE was created with the NO_ALIAS attribute. In this case, the NO_ALIAS attribute is not specified. 2 F$TYPE Returns the data type of a symbol. 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. The string STRING is returned if the symbol is equated to a character string whose characters do not form a valid integer. If the symbol is undefined, a null string ("") is returned. Format F$TYPE(symbol-name) 3 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 types shown in the following table. Symbol Type Lexical Creating Symbol PROCESS_CONTEXT F$PID or F$CONTEXT (with PROCESS context type) CLUSTER_SYSTEM_ F$CSID CONTEXT 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. 3 Argument symbol-name Specifies the name of the symbol to be evaluated. 3 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. 2 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() 3 Return_Value A character string containing the current UIC, including brackets ([ ]). The UIC is returned in the format [group-identifier, member-identifier]. 3 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. 2 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]) 3 Return_Value The integer 0 if the procedure verification setting is off, or the integer 1 if the procedure verification setting is on. 3 Arguments 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. 3 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.
Software development, photography, jokes, ....
Hosting Favorites |
| ANU Internet Services |
| Netim |
| GoDaddy |
| XEL Media |
Blogroll |
| Bomenstichting |
| Google Translate |
| PHP |
| MySQL |
| jQuery |
| jQuery UI |
| YourHead Stacks API |
| Favicon Generator. |
| Password Generator. |
| Check HTTPS problems |
Tweets by MrMacvos
Marc's Place
On this website, Google Analytics is used to track visitor statistics. These are anonymised data about the number of visitors, which pages they visit on this site, from which regions they visit, which web browsers they use, etc.. You will also see non-personalised ads via Google AdSense. Cookies from Paddle or Paypal are placed when you click on a 'Buy now!' or 'Donate!' button, and possible cookies from Disqus when you use that system to comment on one or more blogposts.
Privacy Statement