![[Digital logo]](../../IMAGES/DIGITAL-LOGO.GIF){kind=logo}
![[HR]](../../IMAGES/REDBAR.GIF)
The F$DEVICE function allows wildcard searches based on the device name, the device class, or the device type. To do a search based on device type, you must also specify a device class.
You can use the F$DEVICE function in a loop in a command procedure to return device names that match the specified selection criteria. Each time the F$DEVICE function is executed, it returns the next device on the system that matches the selection criteria. Note that devices are returned in no particular order. After the last device name is returned, the next F$DEVICE function call returns a null string.
This command procedure displays the device names of all the RA60s on a unit numbered 0:
$ START:
$ DEVICE_NAME = F$DEVICE("*0:","DISK","RA60")
$ IF DEVICE_NAME .EQS. "" THEN EXIT
$ SHOW SYMBOL DEVICE_NAME
$ GOTO START
Before processing a file, a command procedure should use the F$SEARCH function to test whether the file exists. For example, the following command procedure uses F$PARSE to apply a device and directory string to the file STATS.DAT. Then the procedure uses the F$SEARCH function to determine whether STATS.DAT is present in DISK3:[JONES.WORK]. If it is, the command procedure processes the file. Otherwise, the command procedure prompts for another input file.
$ FILE = F$PARSE("STATS.DAT","DISK3:[JONES.WORK]",,,"SYNTAX_ONLY")
$ IF F$SEARCH(FILE) .EQS. "" THEN GOTO GET_FILE
$ PROCESS_FILE:
.
.
.
$ GET_FILE:
$ INQUIRE FILE "File name"
$ GOTO PROCESS_FILE
After determining that a file exists, the procedure can use the F$PARSE or the F$FILE_ATTRIBUTES function to get additional information about the file. For example:
$ IF F$SEARCH("STATS.DAT") .EQS. "" THEN GOTO GET_FILE
$ PROCESS_FILE:
$ NAME = F$PARSE("STATS.DAT",, "NAME")
.
.
.
$ GET_FILE:
$ INQUIRE FILE "File name"
$ GOTO PROCESS_FILE
If a command procedure creates files that you do not need after the procedure terminates, delete or purge these files before you exit from the procedure. Use the PURGE command to delete all versions except the most recent one. Use the DELETE command with a version number to delete a specific version of the file or with a wildcard character in the version field to delete all versions of the file.
To avoid error messages when using the DELETE command within a command procedure, use the F$SEARCH function to verify that a file exists before you try to delete it. For example, you can write a command procedure that creates a file named TEMP.DAT only if certain modules are executed. The following line issues the DELETE command only if TEMP.DAT exists:
$ IF F$SEARCH("TEMP.DAT") .NES. "" THEN DELETE TEMP.DAT;*
You can use the following lexical functions to translate logical names:
| F$LOGICAL | Returns the equivalence string for a logical name. |
| F$TRNLNM | Returns either the equivalence string or the requested attributes for a logical name. |
The F$TRNLNM function supersedes the F$LOGICAL function that was used in earlier versions of the OpenVMS operating system. You should use F$TRNLNM (instead of F$LOGICAL) to ensure that your command procedure processes logical names using the current system techniques.
In some situations, you may want to use logical names rather than symbols as variables in command procedures. Programs can access logical names more easily than they can access DCL symbols. Therefore, to pass information to a program that you run from a command procedure, obtain the information using a symbol. Then use the DEFINE command to equate the value of the symbol to a logical name.
You can also use the F$TRNLNM function to assign the value of a logical name to a symbol.
$ ! Make sure that NAMES is defined
$ IF F$TRNLNM("NAMES") .NES. "" THEN GOTO ALL_SET
$ INQUIRE FILE "File with employee names"
$ DEFINE NAMES 'FILE'
$ !
$ ! Run PAYROLL, using the file indicated by NAMES
$ ALL_SET:
$ RUN PAYROLL
.
.
.
$ DEFINE NAMES DISK4:[JONES]EMPLOYEE_NAMES.DAT $ RUN PAYROLL . . . $ FILE = F$TRNLNM(NAMES) $ WRITE SYS$OUTPUT "Finished processing ",FILE
You can use the following lexical functions to manipulate character strings:
| F$CVTIME | Returns information about a time string |
| F$EDIT | Edits a character string |
| F$ELEMENT | Extracts an element from a string in which the elements are separated by delimiters |
| F$EXTRACT | Extracts a section of a character string |
| F$FAO | Formats an output string |
| F$LENGTH | Determines the length of a string |
| F$LOCATE | Locates a character or a substring within a string and returns the offset |
One common reason for examining strings is to determine whether a character (or substring) is present within a character string. To do this, use the F$LENGTH and the F$LOCATE functions. If the value returned by the F$LOCATE function equals the value returned by the F$LENGTH function, then the character you are looking for is not present.
This procedure requires a file name that includes the version number. To determine whether a version number is present, the procedure tests whether a semicolon (;), which precedes a version number in a file name, is included in the file name that the user enters:
$ INQUIRE FILE "Enter file (include version number)"
$ IF F$LOCATE(";", FILE) .EQ. F$LENGTH(FILE) THEN -
GOTO NO_VERSION
.
.
.
The F$LOCATE function returns the offset for the semicolon. Offsets start with 0; thus, if the semicolon were the first character in the string, the F$LOCATE function would return the integer 0. If the semicolon is not present within the string, the F$LOCATE function returns an offset that is one more than the offset of the last character in the string. This value is the same as the length returned by F$LENGTH, which measures the length of the string starting with the number 1.
To extract a portion of a string, use either the F$EXTRACT function or the F$ELEMENT function. Use the F$EXTRACT function to extract a substring that starts at a defined offset. Use the F$ELEMENT function to extract part of a string between two delimiters. In order to use either of these functions, you must know the general format of the string you are parsing. Note that you do not need to use F$EXTRACT or F$ELEMENT to parse file specifications or time strings. Instead, use F$PARSE or F$CVTIME to extract the desired portions of file specifications or time strings.
You can also determine the length of the group name at the same time you extract it.
If a string contains a delimiter that separates different parts of the string, use the F$ELEMENT function to extract the part that you want. You can use F$ELEMENT to obtain different types of access by extracting the portions of the string between the commas. To determine system access, obtain the first element; to determine owner access, obtain the second element; and so on. Note that when you use the F$ELEMENT function, element numbers start with zero. For this reason, use the integer 3 to specify the fourth element.
$ UIC = F$USER()
$ GROUP_LEN = F$LOCATE(",",UIC) - 1
$ GROUP = F$EXTRACT(1,GROUP_LEN, UIC)
$ GOTO 'GROUP'_SECTION
.
.
.
$ WRITERS_SECTION:
.
.
.
$ MANAGERS_SECTION:
.
.
.
$ UIC = F$USER()
$ GROUP = F$EXTRACT(1, F$LOCATE(",",UIC) - 1, UIC)
$ GOTO 'GROUP'_SECTION
$ PROT = F$ENVIRONMENT("PROTECTION")
$ SHOW SYMBOL PROT
PROT = "SYSTEM=RWED, OWNER=RWED, GROUP=RE, WORLD"
$ PROT = F$ENVIRONMENT("PROTECTION")
$ WORLD_PROT = F$ELEMENT(3,",",PROT)
.
.
.
$ PROT = F$ENVIRONMENT("PROTECTION")
$ WORLD_PROT = F$ELEMENT(3,",",PROT)
$ IF F$LOCATE("=", WORLD_PROT) .EQ. F$LENGTH(WORLD_PROT) -
THEN GOTO NO_WORLD_ACCESS
.
.
.
You can use the WRITE command to write a string to a record. To line up columns in a record, you can use the F$FAO function to define record fields and place the process name and user name in these fields. When you use the F$FAO function, use a control string to define the fields in the record; then specify the values to be placed in these fields.
Another way to format fields in a record is to use a character string overlay. Note, however, that the F$FAO function is more powerful than a character string overlay. You can perform a wider range of output operations with the F$FAO function.
$ ! Initialize context symbol to get PID numbers $ CONTEXT = "" $ ! Write headings $ WRITE SYS$OUTPUT "Process Name PID" $ ! $ GET_PID: $ PID = F$PID(CONTEXT) $ IF PID .EQS. "" THEN EXIT $ WRITE SYS$OUTPUT F$GETJPI(PID,"PRCNAM")," ", F$GETJPI(PID,"PID") $ GOTO GET_PID
Process Name PID MARCHESAND 2CA0049C TRACTMEN 2CA0043A FALLON 2CA0043C ODONNELL 2CA00453 PERRIN 2CA004DE CHAMPIONS 2CA004E3
$ ! Initialize context symbol to get PID numbers
$ CONTEXT = ""
$ ! Write headings
$ WRITE SYS$OUTPUT "Process Name PID"
$ !
$ GET_PID:
$ PID = F$PID(CONTEXT)
$ IF PID .EQS. "" THEN EXIT
$ LINE = F$FAO("!16AS !12AS", F$GETJPI(PID,"PRCNAM"), F$GETJPI(PID,"PID"))
$ WRITE SYS$OUTPUT LINE
$ GOTO GET_PID
Process Name PID MARCHESAND 2CA0049C TRACTMEN 2CA0043A FALLON 2CA0043C ODONNELL 2CA00453 PERRIN 2CA004DE CHAMPIONS 2CA004E3
$ ! Initialize context symbol to get PID numbers $ CONTEXT = "" $ ! Write headings $ WRITE SYS$OUTPUT "Process Name PID" $ ! $ GET_PID: $ PID = F$PID(CONTEXT) $ IF PID .EQS. "" THEN EXIT $ RECORD[0,16]:= 'F$GETJPI(PID,"PRCNAM")' $ RECORD[17,12]:= 'F$GETJPI(PID,"PID")' $ WRITE SYS$OUTPUT RECORD $ GOTO GET_PID
Process Name PID MARCHESAND 2CA0049C TRACTMEN 2CA0043A FALLON 2CA0043C ODONNELL 2CA00453 PERRIN 2CA004DE CHAMPIONS 2CA004E3
You can use the following lexical functions to convert data from strings to integers and from integers to strings:
| F$CVSI | Extracts bit fields from a character string and converts the result, as a signed value, to an integer |
| F$CVUI | Extracts bit fields from a character string and converts the result, as an unsigned value, to an integer |
| F$INTEGER | Converts a string expression to an integer |
| F$STRING | Converts an integer expression to a string |
| F$TYPE | Determines the data type of a symbol |
Use the F$INTEGER and F$STRING functions to convert between integers and strings. For example, the following command procedure converts data types. If you enter a string, the command procedure shows the integer equivalent. If you enter an integer, the command procedure shows the string equivalent. Note how the F$TYPE function is used to form a label name in the GOTO statement; F$TYPE returns "STRING" or "INTEGER" depending on the data type of the symbol.
$ IF P1 .EQS. "" THEN INQUIRE P1 "Value to be converted" $ GOTO CONVERT_'F$TYPE(P1)' $ $ CONVERT_STRING: $ WRITE SYS$OUTPUT "The string ''P1' is converted to ''F$INTEGER(P1)'" $ EXIT $ $ CONVERT_INTEGER: $ WRITE SYS$OUTPUT "The integer ''P1' is converted to ''F$STRING(P1)'" $ EXIT
Some commands, such as INQUIRE and READ, accept only string data. If you use these commands to obtain data that you want to evaluate as an integer expression, use the F$INTEGER function to convert and evaluate this data.
Note that you must place apostrophes (' ') around the symbol EXP when you use it as an argument for the F$INTEGER function. This causes DCL to substitute the value for EXP during the first phase of symbol substitution.
In the following example, the F$INTEGER function is used to evaluate an integer expression:
$ INQUIRE EXP "Enter integer expression"
$ RES = F$INTEGER('EXP')
$ WRITE SYS$OUTPUT "Result is",RES
The output from this command procedure would be as follows:
Enter integer expression: 9 + 7 Result is 16
The value "9 + 7" is substituted. When the F$INTEGER function processes the argument "9 + 7," it evaluates the expression and returns the correct result.
Use the F$TYPE function to determine whether a symbol exists. The F$TYPE function returns a null string if a symbol is undefined. For example:
. . . $ IF F$TYPE(TEMP) .EQS. "" THEN TEMP = "YES" $ IF TEMP .EQS. "YES" THEN GOTO TEMP_SEC . . .
This procedure tests whether the symbol TEMP has been previously defined. If it has, then the current value of TEMP is retained. If TEMP is not defined, then the IF statement assigns the value "YES" to TEMP.
A process is an environment created by the OpenVMS operating system that lets you interact with the system. This chapter describes:
For additional information on the commands described in this chapter, refer to online Help or the OpenVMS DCL Dictionary.
The system creates a process for you when you perform one of the following tasks:
The following sections describe how to interpret your process context.
Characteristics that a process uses, such as privileges, symbols, and logical names, form a process context. To display the process context for your current process, enter the SHOW PROCESS/ALL command.
The following example shows a process context:
11-DEC-1996 13:30:37.12 (1) User: CLEAVER (2) Process ID: 24E003DC (3)
Node: ZEUS Process name: CLEAVER_1
Terminal: (4)
User Identifier: [DOC,CLEAVER] (5)
Base priority: 4 (6)
Default file spec: DISK1:[CLEAVER] (7)
Process Quotas: (8)
Account name: DOC
CPU limit: Infinite Direct I/O limit: 18
Buffered I/O byte count quota: 31808 Buffered I/O limit: 25
Timer queue entry quota: 10 Open file quota: 57
Paging file quota: 22276 Subprocess quota: 4
Default page fault cluster: 64 AST quota: 38
Enqueue quota: 600 Shared file limit: 0
Max detached processes: 0 Max active jobs: 0
Accounting information: (9)
Buffered I/O count: 140 Peak working set size: 383
Direct I/O count: 7 Peak virtual size: 2336
Page faults: 304 Mounted volumes: 0
Images activated: 1
Elapsed CPU time: 0 00:00:00.55
Connect time: 0 00:00:22.76
Process privileges: (10)
GROUP may affect other processes in same group
TMPMBX may create temporary mailbox
OPER operator privilege
NETMBX may create network device
Process rights identifiers: (11)
INTERACTIVE
LOCAL
SYS$NODE_ZEUS
Process Dynamic Memory Area (12)
Current Size (bytes) 25600 Current Total Size (pages) 50
Free Space (bytes) 19592 Space in Use (bytes) 6008
Size of Largest Block 19520 Size of Smallest Block 24
Number of Free Blocks 3 Free Blocks LEQU 32 Bytes 1
Processes in this tree: (13)
CLEAVER
CLEAVER_1 (*)
As you examine the example, note the following:
A detached process is either interactive or noninteractive, depending on the parent process. Either you or the operating system perform the login, depending on the argument you provided to the DCL command RUN or the Create Process system service ($CREPRC). (Both RUN and $CREPRC execute the LOGINOUT.EXE image in SYS$SYSTEM.)
The SPAWN command enables you to create a subprocess of your current process. Within this subprocess, you can interact with the system and log out of the subprocess to return to your parent process or switch between your parent process and subprocesses. Only one of your processes is executing at any time.
Each user on the system is represented by a job tree. A job tree is a hierarchy of all your processes and subprocesses with your main process at the top. A subprocess is dependent on the parent process and is deleted when the parent process exits. By default, the subprocess assumes the name of the parent process followed by an underscore and a unique number. For example, if the parent process name is DOUGLASS, the subprocesses are named DOUGLASS_1, DOUGLASS_2, and so on.
To interrupt a task, perform a second task, then return to the original task, you can use Ctrl/Y to interrupt the first task, spawn a subprocess to perform the second task, exit from the subprocess, and then enter the CONTINUE command to return to the first task. By default, when you create a subprocess, the parent process hibernates and you are given control at DCL level within the subprocess. Your default directory is the current directory of the parent process. For example, if you press Ctrl/Y to interrupt an EVE editing session, enter the CONTINUE command and press Ctrl/W to refresh the screen.
To perform a second task while continuing to work on your original task, you can create the subprocess with the SPAWN/NOWAIT command. SPAWN/NOWAIT generates a noninteractive, batch-like subprocess and is used to execute only commands that do not require input.
6489P034.HTM OSSG Documentation 22-NOV-1996 13:17:28.03
Copyright © Digital Equipment Corporation 1996. All Rights Reserved.