![[Digital logo]](../../IMAGES/DIGITAL-LOGO.GIF){kind=logo}
![[HR]](../../IMAGES/REDBAR.GIF)
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
#3In 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 ("").
! 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
#4This 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.
$ 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.
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).
F$GETSYI (item [,node-name] [,cluster-id])
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.You can specify the items in Table DCLI-12 only for your local node; you cannot specify the node argument with these items. You can specify these items whether or not you are in an OpenVMS Cluster system.
You can specify the items in Table DCLI-13 for either your local node or for another node in your OpenVMS Cluster system. The information in this table is returned for your local node if you do not specify the node-name argument; the information is returned for the specified node if you include the node-name argument. Your system must be a member of an OpenVMS Cluster system to specify the items in this table, except for CLUSTER_MEMBER. You can specify CLUSTER_MEMBER whether or not your system is a member of an OpenVMS Cluster system.
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.)You can request information about another node in your OpenVMS Cluster system only when you specify an item from Table DCLI-13. If you do not specify a node, the default is the current node.
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.)You can request information about another node in your OpenVMS Cluster system only when you specify an item from Table DCLI-13. If you do not specify a node, the default is the current node.
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.
The F$GETSYI lexical function invokes the $GETSYI system service to return status and identification information about the local system (or about a node in the local OpenVMS Cluster, if your system is part of a cluster). The F$GETSYI function returns information on the items that can be specified with the $GETSYI system service. For more information on the $GETSYI system service, see the OpenVMS System Services Reference Manual.You can specify the node for which you want information by supplying either the node-name or the cluster-id argument, but not both.
Table DCLI-12 lists the items you can specify with the F$GETSYI lexical function to get information about your local node. Table DCLI-13 lists the items you can specify to get information about either your local node or another node in your OpenVMS Cluster system.
Table DCLI-12 F$GETSYI Items for the Local Node Only Item Return Type Information Returned ACTIVECPU_CNT Integer The count of CPUs actively participating in the current boot of a symmetric multiprocessing (SMP) system. ARCHFLAG String Architecture flags for the system. ARCH_NAME String Name of CPU architecture; Alpha for OpenVMS Alpha, VAX for OpenVMS VAX. ARCH_TYPE Integer Type of CPU architecture; 1 for VAX, 2 for Alpha. AVAILCPU_CNT Integer The count of CPUs recognized in the system. BOOTTIME String The time the system was booted. CHARACTER_EMULATED String TRUE or FALSE to indicate whether the character string instructions are emulated on the CPU. ++CONSOLE_VERSION String Console firmware version. CONTIG_GBLPAGES Integer Total number of free, contiguous global pages. +CPU Integer On VAX, the processor type, as represented in the processor's system identification (SID) register. For example, the integer 1 represents a VAX-11/780 and the integer 6 represents a VAX 8530, VAX 8550, VAX 8700, or VAX 8800. ++CPUTYPE Integer On Alpha, the processor type, as stored in the hardware restart parameter block (HWRPB). The value of 2 represents a DECchip 21064 processor. DECIMAL_EMULATED String TRUE or FALSE to indicate whether the decimal string instructions are emulated on the CPU. D_FLOAT_EMULATED String TRUE or FALSE to indicate whether the D_floating instructions are emulated on the CPU. ERRORLOGBUFFERS Integer Number of system pages (on VAX) or pagelets (on Alpha) to be used as errorlog buffers. F_FLOAT_EMULATED String TRUE or FALSE to indicate whether the F_floating instructions are emulated on the CPU. FREE_GBLPAGES Integer Current count of free global pages. FREE_GBLSECTS Integer Current count of free global section table entries. G_FLOAT_EMULATED String TRUE or FALSE to indicate whether the G_floating instructions are emulated on the CPU. ++GH_RSRVPGCNT Integer On Alpha, number of pages covered by granularity hints to reserve for use by the INSTALL utility after system startup has completed. ++ITB_ENTRIES Integer On Alpha, number of I-stream translation buffer entries which support granularity hints to be allocated for resident code. MEMSIZE Integer Number of pages of memory in the system configuration. PAGEFILE_FREE Integer Number of free pages in the currently installed paging files. PAGEFILE_PAGE Integer Number of pages in the currently installed paging files. ++PALCODE_VERSION String Version of the PALCODE (privileged architectural library) on your Alpha system. QUANTUM Integer Maximum amount of processor time a process can receive while other processes are waiting. SCS_EXISTS String TRUE or FALSE to indicate whether the system communication subsystem (SCS) is currently loaded on a VAX node. SID Integer System identification register. On Alpha, returns a value where all fields are zero except the CPU type field, which always contains the value of 256. SWAPFILE_FREE Integer Number of free pages in the currently installed swapping files. SWAPFILE_PAGE Integer Number of pages in the currently installed swapping files. SYSTEM_RIGHTS String The contents of the system rights list on the local system. If you specify a remote system, a null string ("") is returned. This item code returns a list of identifier names separated by commas (,). ++SYSTYPE Integer On Alpha, the family or system hardware platform. For example, the integer 2 represents a DEC 4000, the integer 3 represents a DEC 7000 or DEC 10000, and the integer 4 represents a DEC 3000. USED_GBLPAGCNT Integer Number of pages currently in use in the global page table. USED_GBLPAGMAX Integer Maximum number of pages ever in use in the global page table. VERSION String Version of OpenVMS in use (8-character string filled with trailing blanks).
+VAX specific.
++Alpha specific.
Table DCLI-13 F$GETSYI Items for the Local Node or for Other Nodes in the OpenVMS Cluster Item Return Type Information Returned CLUSTER_EVOTES Integer Total number of votes in the cluster. CLUSTER_FSYSID String System identification number for first node to boot in the cluster (the founding node). This number is returned as a character string containing a hexadecimal number. CLUSTER_FTIME String The time when the first node in the cluster was booted. CLUSTER_MEMBER String TRUE or FALSE if the node is a member of the local cluster. CLUSTER_NODES Integer Total number of nodes in the cluster, as an integer. CLUSTER_QUORUM Integer Total quorum for the cluster. CLUSTER_VOTES Integer Total number of votes in the cluster. DECNET_FULLNAME String The node name of a DECnet Phase IV system or the node full name of a DECnet/OSI system. HW_MODEL Integer An integer that identifies the node's Alpha or VAX model type. An integer greater than 1023 represents the Alpha operating system and an integer less than or equal to 1023 represents the VAX operating system. HW_NAME String The Alpha or VAX model name. NODENAME String Node name (does not include the following double colon). NODE_AREA Integer The DECnet area for the target node. NODE_CSID String The CSID of the specified node, as a string containing a hexadecimal number. The CSID is a form of system identification. NODE_EVOTES Integer Number of votes allotted to the node. NODE_HWTYPE String Hardware type of the specified node. NODE_HWVERS String Hardware version of the specified node. NODE_NUMBER Integer The DECnet number for the specified node. NODE_QUORUM Integer Quorum that the node has. NODE_SWINCARN String Software incarnation number for the specified node. This number is returned as a string containing a hexadecimal number. NODE_SWTYPE String Type of operating system software used by the specified node. NODE_SWVERS String Software version of the specified node. NODE_SYSTEMID String System identification number for the specified node. This number is returned as a string containing a hexadecimal number. NODE_VOTES Integer Number of votes allotted to the node. ++REAL_CPUTYPE String The actual CPU type of the primary CPU of the system. VECTOR_EMULATOR Boolean Flag indicating the presence of the VAX vector instruction emulator facility (VVIEF) in the system. VP_MASK Integer Mask indicating which processors in the system have vector coprocessors. VP_NUMBER Integer Number of vector processors in the system.
++Alpha specific.
#1
$ SYSID = F$GETSYI("SID")
$ SHOW SYMBOL SYSID
SYSID = 19923201 Hex = 01300101 Octal = 000401
#2This 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.
$ MEM = F$GETSYI("CLUSTER_MEMBER", "LONDON")
$ SHOW SYMBOL MEM
MEM = "TRUE"
#3This 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.
$ 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.
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.
F$IDENTIFIER (identifier,conversion-type)
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".
#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]
#2This 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].
$ 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.
Returns the integer equivalent of the result of the specified expression.
F$INTEGER (expression)
expression
Specifies the expression to be evaluated. Specify either an integer or a character string expression.If you specify an integer expression, the F$INTEGER function evaluates the expression and returns the result. If you specify a string expression, the F$INTEGER function evaluates the expression, converts the resulting string to an integer, and returns the result.
After evaluating a string expression, the F$INTEGER function converts the result to an integer in the following way. If the resulting string contains characters that form a valid integer, the F$INTEGER function returns the integer value. If the string contains characters that do not form a valid integer, the F$INTEGER function returns the integer 1 if the string begins with T, t, Y, or y. The function returns the integer 0 if the string begins with any other character.
$ 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.
Returns the length of the specified character string.
F$LENGTH (string)
string
Specifies the character string whose length is being determined. Specify the string argument as a character string expression.
$ 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.
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.
F$LOCATE (substring,string)
If the substring is not found, the F$LOCATE function returns an offset of the last character in the character string plus 1. (This equals the length of the string.)
substring
Specifies the character string that you want to locate within the string specified in the string argument.string
Specifies the character string to be edited by F$LOCATE.
#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.
Previous | Next | Contents | [Home] | [Comments] | [Ordering info] | [Help]
9996P028.HTM OSSG Documentation 26-NOV-1996 11:17:41.27Copyright © Digital Equipment Corporation 1996. All Rights Reserved.