Document revision date: 30 March 2001

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;*

17.5 Translating Logical Names

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.

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 or ASSIGN command to equate the value of the symbol to a logical name.

You can also use the F$TRNLNM function to determine the value of a logical name and then assign the value to a symbol.

The following example tests whether the logical name NAMES has been defined. If it has, the procedure runs PAYROLL.EXE. Otherwise, the procedure obtains a value for the symbol FILE and uses this value to create the logical name NAMES. PAYROLL.EXE uses the logical name NAMES to refer to the file of employee names.

$ ! 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 . . .

This command procedure defines a logical name that is used in the program PAYROLL:

$ DEFINE NAMES DISK4:[JONES]EMPLOYEE_NAMES.DAT $ RUN PAYROLL . . . $ WRITE SYS$OUTPUT "Finished processing ",F$TRNLNM("NAMES")

At the end of the procedure, the WRITE command displays a message indicating that the file was processed.

17.6 Manipulating Strings

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

17.6.1 Determining Presence of Strings or Characters

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.

The following 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.

17.6.2 Extracting Parts of Strings

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.

The following command procedure uses the F$EXTRACT function to extract the group portion of the UIC. This allows the procedure to execute a different set of commands depending on the user's UIC group.

$ UIC = F$USER() $ GROUP_LEN = F$LOCATE(",",UIC) - 1 $ GROUP = F$EXTRACT(1,GROUP_LEN, UIC) $ GOTO 'GROUP'_SECTION . . . $ WRITERS_SECTION: . . . $ MANAGERS_SECTION: . . .

First, the procedure determines the UIC with the F$USER function. Next, the procedure determines the length of the group name by using F$LOCATE to locate the offset of the comma. The comma separates the group from the user portion of a UIC. Everything between the left bracket and the comma is part of the group name. For example, the group name from the UIC [WRITERS,SMITH] is WRITERS.

After determining the length, the procedure extracts the name of the group with the F$EXTRACT function. The name starts with offset 1 and ends with the character before the comma. Finally, the procedure directs execution to the appropriate label.

The following example shows how to determine the length of a group name at the same time it is being extracted:

$ UIC = F$USER() $ GROUP = F$EXTRACT(1, F$LOCATE(",",UIC) - 1, UIC) $ GOTO 'GROUP'_SECTION

The following example shows how each type of access in a protection code is separated by a comma:

$ PROT = F$ENVIRONMENT("PROTECTION") $ SHOW SYMBOL PROT PROT = "SYSTEM=RWED, OWNER=RWED, GROUP=RE, WORLD"

The commands in this example extract the world access portion (the fourth element) from the default protection code:

$ PROT = F$ENVIRONMENT("PROTECTION") $ WORLD_PROT = F$ELEMENT(3,",",PROT) . . .

The F$ELEMENT function returns everything between the third comma and the end of the string. Thus, if your default protection allowed read access for world users, the string "WORLD=R" would be returned.

After you obtain the world access string, you may need to examine it further. For example:

$ 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 . . .

17.6.3 Formatting Output Strings

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.

The command procedure shown in the following example uses the WRITE command to display the process name and PID number for processes on the system:

$ ! 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

Note that the output from the WRITE command inserts five spaces between the process name and the user name but the columns do not line up:

Process Name PID MARCHESAND 2CA0049C TRACTMEN 2CA0043A FALLON 2CA0043C ODONNELL 2CA00453 PERRIN 2CA004DE CHAMPIONS 2CA004E3

The command procedure in this example uses the F$FAO function to define a 16-character field and a 12-character field. The F$FAO function places the process name in the first field, skips a space, and then places the PID number in the second field:

$ ! 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

Now when you execute the procedure, the columns will align:

Process Name PID MARCHESAND 2CA0049C TRACTMEN 2CA0043A FALLON 2CA0043C ODONNELL 2CA00453 PERRIN 2CA004DE CHAMPIONS 2CA004E3

The following example uses an overlay to place the process name in the first 16 characters (starting at offset 0) of the symbol RECORD. Then the PID number is placed in the next 12 characters (starting at offset 17).

$ ! 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

This procedure produces the same type of formatted columns you created with the F$FAO function:

Process Name PID MARCHESAND 2CA0049C TRACTMEN 2CA0043A FALLON 2CA0043C ODONNELL 2CA00453 PERRIN 2CA004DE CHAMPIONS 2CA004E3

17.7 Manipulating Data Types

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

17.7.1 Converting Data Types

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

17.7.2 Evaluating Expressions

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.

17.7.3 Determining Whether a Symbol Exists

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:

• Interpreting your process context
• Using subprocesses
• Connecting to disconnected processes on virtual terminals
• Working with batch jobs

For additional information about the commands described in this chapter, refer to online Help or the OpenVMS DCL Dictionary.

How Processes Are Created

The system creates a process for you when you perform one of the following tasks:

• Logging in
  The system creates a process for each interactive user.
• Submitting a batch job
  The system creates a process for each batch job. When the batch job is completed, the system deletes the process.
• Spawning a subprocess
  The system creates a process when you use the SPAWN command.
• Running a program
  The system creates a process when you run a program using either the /DETACHED qualifier or the /UIC=uic qualifier.

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-1999 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:

1. Current date and time
   The date and time when the SHOW PROCESS/ALL command is executed.
2. User name
   The user name assigned to the account that is associated with the process.
3. Process identification (PID) number
   A unique number assigned to the process by the system. The SHOW PROCESS command displays the PID number as a hexadecimal number.

4. Process name
   The name assigned to the process. Because process names are unique (within a specific UIC group), the first process logged in under an account is assigned the user name. Subsequent processes logged in under the same account are assigned the terminal name. You can change your process name with the DCL command SET PROCESS/NAME.
5. User identification code (UIC)
   The group and member numbers (or letters) assigned to the account that is associated with the process (for example, [DOC,CLEAVER]). Part of your UIC identifies the group to which you belong. Within a group, users are allowed to share files or system resources more freely than between groups.
6. Priority
   The current priority of the process.
7. Default file specification
   The current device and directory. Change your current defaults with the DCL command SET DEFAULT.
8. Process quotas
   The quotas (limits) associated with the process. Examine these quotas with the /QUOTAS or /ALL qualifiers of the SHOW PROCESS command.
9. Accounting information
   The continuously updated account of the process' use of memory and CPU time. Examine this information with the /ACCOUNTING or /ALL qualifiers of the SHOW PROCESS command.
10. Process privileges
    The privileges granted to your processes. Privileges restrict the performance of certain system activities to certain users. Examine your privileges with the /PRIVILEGES or /ALL qualifiers of the SHOW PROCESS command.
11. Process rights identifiers
    System-defined identifiers that are used in conjunction with access control list (ACL) protection. Identifiers provide the means of specifying the users in an ACL. An ACL is a security tool that defines the kinds of access to be granted or denied to users of an object, such as a file, device, or mailbox.
12. Process dynamic memory area
    The process' current use of dynamic memory. Dynamic memory is allocated by the system to an image when that image is executing. When that memory is no longer needed by one process, the system allocates it to another process. Examine this information with the /MEMORY or /ALL qualifiers of the SHOW PROCESS command.
13. Processes in this tree
    A list of subprocesses belonging to the parent process. An asterisk (*) appears after the current process. Examine this list with the SHOW PROCESS/SUBPROCESSES or /ALL command.

	privacy and legal statement
6489PRO_047.HTML