 |
OpenVMS DCL Dictionary
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.
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])
Return Value
Either an integer or a character string, depending on the item you
request.
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 an OpenVMS Cluster). Specify the item as a character string
expression.
You can also specify any of the system parameters listed in the
OpenVMS System Management Utilities Reference Manual.
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.
cluster-id
Specifies the cluster node identification number for which the
information is to be returned.
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.
Description
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
about the $GETSYI system service, refer to 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-10 lists the items you can specify with the F$GETSYI lexical
function.
Table DCLI-10 F$GETSYI Items
| 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.
|
|
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.
|
|
+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.
|
|
CWLOGICALS
|
Boolean
|
Flag indicating that the clusterwide logical name database has been
initialized on the CPU.
|
|
DECIMAL_EMULATED
|
String
|
TRUE or FALSE to indicate whether the decimal string instructions are
emulated on the CPU.
|
|
DECNET_FULLNAME
|
String
|
The node name of a DECnet Phase IV system or the node full name of a
DECnet/OSI system.
|
|
DECNET_VERSION
|
String
|
Returns information on the particular version and ECO level of the
DECnet package installed on the local system. This item returns a
string containing a hexidecimal number, using the following format:
- Byte 0 = Customer ECO
- Byte 1 = DECnet ECO
- Byte 2 = DECnet phase (4 for Phase IV, 5 for DECnet-Plus for
OpenVMS)
- Byte 3 = Reserved
To distinguish Phase IV from DECnet-Plus for OpenVMS, use the byte
containing the DECnet version (byte 2).
|
|
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.
|
|
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.
|
|
++ITB_ENTRIES
|
Integer
|
On Alpha, number of I-stream translation buffer entries that support
granularity hints to be allocated for resident code.
|
|
MEMSIZE
|
Integer
|
Number of pages of memory in the system configuration.
|
|
MULTITHREAD
|
Integer
|
Value of the MULTITHREAD system parameter.
|
|
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_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.
|
|
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.
|
|
PAGE_SIZE
|
Integer
|
Indicates the number of bytes in a physical page.
|
|
++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.
|
|
++RAD_CPUS
|
Integer
|
Returns list of RAD,CPU pairs, separated by commas. Resource affinity
domains (RADs) are supported only on AlphaServer GS160 systems.
|
|
++RAD_MEMSIZE
|
Integer
|
Returns list of RAD,PAGES pairs, separated by commas. Supported only on
AlphaServer GS160 systems.
|
|
++RAD_MAX_RADS
|
Integer
|
Returns the maximum number of RADS possible on this platform. Supported
only on AlphaServer GS160 systems, and the value is always 8 (regardless of
number of quad building blocks (QBBs) physically present).
|
|
++RAD_SHMEMSIZE
|
Integer
|
Returns list of RAD,PAGES pairs, separated by commas. Supported only on
AlphaServer GS160 systems.
|
|
++REAL_CPUTYPE
|
String
|
The actual CPU type of the primary CPU of the system.
|
|
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
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.
|
|
VECTOR_EMULATOR
|
Boolean
|
Flag indicating the presence of the VAX vector instruction emulator
facility (VVIEF) in the system.
|
|
VERSION
|
String
|
Version of OpenVMS in use (8-character string filled with trailing
blanks).
|
|
VP_MASK
|
Integer
|
Mask indicating which processors in the system have vector coprocessors.
|
|
VP_NUMBER
|
Integer
|
Number of vector processors in the system.
|
+VAX specific.
++Alpha specific.
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.
| #4 |
$ DECNETVERS = F$GETSYI("DECNET_VERSION")
$ SHOW SYMBOL DECNETVERS
DECNETVERS = "00050D01"
$ DECNETPHASE = F$INTEGER(F$EXTRACT(2,2,DECNETVERS))
$ SHOW SYMBOL DECNETPHASE
DECNETPHASE = 5 Hex = 00000005 Octal = 00000000005
|
This example shows how to use F$GETSYI to return the DECnet version,
using the DECNET_VERSION item.
| #5 |
$ RADCPU = F$GETSYI("RAD_CPUS")
$ SHOW SYMBOL RADCPU
0,0,0,1,1,4,1,5
|
This example uses the system parameter RAD_CPUS as an argument for the
F$GETSYI function. This argument returns a list of RAD,CPU pairs,
separated by commas. In this example, the first RAD,CPU pair is 0,0,
the second pair is 0,1, and so forth.
This parameter is supported only on AlphaServer GS160 systems.
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)
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).
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, refer to 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".
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.
|
