 |
HP OpenVMS System Services Reference Manual
$ERASE
The Erase service deletes a disk file and removes the file's directory
entry specified in the path to the file. If additional directory
entries have been created for this file by the Enter service, you must
use the Remove service to delete them.
For additional information about this service, see the OpenVMS Record Management Services Reference Manual.
$EXIT
Initiates image rundown when the current image in a process completes
execution. Control normally returns to the command interpreter.
Format
SYS$EXIT [code]
C Prototype
int sys$exit (unsigned int code);
Argument
code
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Longword value to be saved in the process header as the completion
status of the current image. If you do not specify this argument in a
macro call, a value of 1 is passed as the completion code for VAX MACRO
and VAX BLISS--32, and a value of 0 is passed for other languages. You
can test this value at the command level to provide conditional command
execution.
Description
The $EXIT service is unlike all other system services in that it does
not return status codes in R0 or anywhere else. The $EXIT service does
not return control to the caller; it performs an exit to the command
interpreter or causes the process to terminate if no command
interpreter is present.
Required Access or Privileges
None
Required Quota
None
Related Services
$CANEXH, $CREPRC, $DCLEXH, $DELPRC, $FORCEX, $GETJPI, $GETJPIW, $HIBER,
$PROCESS_SCAN, $RESUME, $SETPRI, $SETPRN, $SETPRV, $SETRWM, $SUSPND,
$WAKE
$EXPREG
Adds a specified number of new virtual pages to a process's program
region or control region for the execution of the current image.
Expansion occurs at the current end of that region's virtual address
space.
Format
SYS$EXPREG pagcnt ,[retadr] ,[acmode] ,[region]
C Prototype
int sys$expreg (unsigned int pagcnt, struct _va_range *retadr, unsigned
int acmode, char region);
Arguments
pagcnt
| OpenVMS usage: |
longword_unsigned |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Number of pagelets to add to the current end of the program or control
region. The pagcnt argument is a longword value
containing this number.
On Alpha and Integrity server systems, the specified value is rounded
up to an even multiple of the CPU-specific page size.
retadr
| OpenVMS usage: |
address_range |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by reference |
Starting and ending process virtual addresses of the pages that $EXPREG
has actually added. The retadr argument is the address
of a 2-longword array containing, in order, the starting and ending
process virtual addresses.
acmode
| OpenVMS usage: |
access_mode |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Access mode to be associated with the newly added pages. The
acmode argument is a longword containing the access
mode.
The most privileged access mode used is the access mode of the caller.
The newly added pages are given the following protection: (1) read and
write access for access modes equal to or more privileged than the
access mode used in the call, and (2) no access for access modes less
privileged than that used in the call.
region
| OpenVMS usage: |
longword_unsigned |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Number specifying which program region is to be expanded. The
region argument is a longword value. A value of 0 (the
default) specifies that the program region (P0 region) is to be
expanded. A value of 1 specifies that the control region (P1 region) is
to be expanded.
Description
The Expand Program/Control Region service adds a specified number of
new virtual pages to a process's program region or control region for
the execution of the current image. Expansion occurs at the current end
of that region's virtual address space.
The new pages, which were previously inaccessible to the process, are
created as demand-zero pages.
Because the bottom of the user stack is normally located at the end of
the control region, expanding the control region is equivalent to
expanding the user stack. The effect is to increase the available stack
space by the specified amount.
The starting address returned is always the first available page in the
designated region; therefore, the ending address is smaller than the
starting address when the control region is expanded and is larger than
the starting address when the program region is expanded.
If an error occurs while pages are being added, the
retadr argument (if specified) indicates the pages
that were successfully added before the error occurred. If no pages
were added, both longwords of the retadr argument
contain the value --1.
Required Access or Privileges
None
Required Quota
The process's paging file quota (PGFLQUOTA) must be sufficient to
accommodate the increased size of the virtual address space.
Related Services
$ADJSTK, $ADJWSL, $CRETVA, $CRMPSC, $DELTVA, $DGBLSC, $LCKPAG, $LKWSET,
$MGBLSC, $PURGWS, $SETPRT, $SETSTK, $SETSWM, $ULKPAG, $ULWSET, $UPDSEC,
$UPDSECW
Typically, the information returned in the location addressed by the
retadr argument (if specified) can be used as the
input range to the Delete Virtual Address Space ($DELTVA) service.
Condition Values Returned
|
SS$_NORMAL
|
The service completed successfully.
|
|
SS$_ACCVIO
|
The return address array cannot be written by the caller.
|
|
SS$_EXQUOTA
|
The process exceeded its paging file quota.
|
|
SS$_ILLPAGCNT
|
The specified page count was less than 1 or would cause the program or
control region to exceed its maximum size.
|
|
SS$_INSFWSL
|
The process's working set limit is not large enough to accommodate the
increased virtual address space.
|
|
SS$_VASFULL
|
The process's virtual address space is full. No space is available in
the process page table for the requested regions.
|
$EXPREG_64 (Alpha and Integrity servers)
On Alpha and Integrity server systems, adds a specified number of
demand-zero allocation pages to a process's virtual address space for
the execution of the current image. Expansion occurs at the next free
available address within the specified region.
This service accepts 64-bit addresses.
Format
SYS$EXPREG_64 region_id_64 ,length_64 ,acmode ,flags ,return_va_64
,return_length_64
C Prototype
int sys$expreg_64 (struct _generic_64 *region_id_64, unsigned __int64
length_64, unsigned int acmode, unsigned int flags, void
*(*(return_va_64)), unsigned __int64 *return_length_64);
Arguments
region_id_64
| OpenVMS usage: |
region identifier |
| type: |
quadword (unsigned) |
| access: |
read only |
| mechanism: |
by 32- or 64-bit reference |
The region ID associated with the virtual address range to be expanded.
The file VADEF.H in SYS$STARLET_C.TLB and the $VADEF macro in
STARLET.MLB define a symbolic name for each of the three default
regions in P0, P1, and P2 space.
The following region IDs are defined:
| Symbol |
Region |
|
VA$C_P0
|
Program region
|
|
VA$C_P1
|
Control region
|
|
VA$C_P2
|
64-bit program region
|
Other region IDs, as returned by the $CREATE_REGION_64 service, can be
specified.
length_64
| OpenVMS usage: |
byte count |
| type: |
quadword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Length of the virtual address space to be created. The length specified
must be a multiple of CPU-specific pages.
acmode
| OpenVMS usage: |
access_mode |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Access mode associated with the call to $EXPREG_64. The access mode
determines the owner mode of the pages as well as the read and write
protection on the pages. The acmode argument is a
longword containing the access mode. The $PSLDEF macro defines symbols
for the four access modes.
The $EXPREG_64 service uses whichever of the following two access modes
is least privileged:
- The access mode specified by the acmode argument.
- The access mode of the caller. The protection of the pages is
read/write for the resultant access mode and those more privileged.
Address space cannot be created within a region that has a create mode
associated with it that is more privileged than the caller's mode. The
condition value SS$_IVACMODE is returned if the caller is less
privileged than the create mode for the region.
flags
| OpenVMS usage: |
mask_longword |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Flag mask controlling the characteristics of the demand-zero pages
created. The flags argument is a longword bit vector
in which each bit corresponds to a flag. The $VADEF macro and the
VADEF.H file define a symbolic name for each flag. You construct the
flags argument by performing a logical OR operation on
the symbol names for all desired flags.
All bits in the flags argument are reserved for future
use by HP and should be specified as 0. The condition value SS$_IVVAFLG
is returned if any bits are set.
return_va_64
| OpenVMS usage: |
address |
| type: |
quadword address |
| access: |
write only |
| mechanism: |
by 32- or 64-bit reference |
The lowest process virtual address of a created virtual address range.
The return_va_64 argument is the 32- or 64-bit virtual
address of a naturally aligned quadword into which the service returns
the virtual address.
return_length_64
| OpenVMS usage: |
byte count |
| type: |
quadword (unsigned) |
| access: |
write only |
| mechanism: |
by 32- or 64-bit reference |
The 32- or 64-bit virtual address of a naturally aligned quadword into
which the service returns the length in bytes of the virtual address
range created.
Description
The Expand Virtual Address Space service is a kernel mode service that
can be called from any mode. This service adds a range of demand-zero
allocation pages to a process's virtual address space for the execution
of the current image. Expansion occurs at the next free available
address within the specified region. The new pages, which were
previously inaccessible to the process, are created as demand-zero
pages.
The returned address is always the lowest virtual address in the range
of pages created. The returned length is always an unsigned byte count
indicating the length of the range of pages created.
Successful return status from $EXPREG_64 Expand Virtual Address service
means that the specified region's virtual address space was expanded by
the number of bytes specified in the length_64
argument.
If the condition value SS$_ACCVIO is returned by this service, a value
cannot be returned in the memory locations pointed to by the
return_va_64 and return_length_64
arguments. If a condition value other than SS$_ACCVIO is returned, the
returned address and returned length indicate the pages that were
successfully added before the error occurred. If no pages were added,
the return_va_64 argument will contain the value --1,
and a value cannot be returned in the memory location pointed
to by the return_length_64 argument.
Required Privileges
None
Required Quota
The working set quota (WSQUOTA) of the process must be sufficient to
accommodate the increased length of the process page table required by
the increase in virtual address space.
The process's paging file quota (PGFLQUOTA) must be sufficient to
accommodate the increased size of the virtual address space.
Related Services
$CREATE_BUFOBJ_64, $CREATE_REGION_64, $CRETVA_64, $DELETE_REGION_64,
$DELTVA_64, $LCKPAG_64, $LKWSET_64, $PURGE_WS, $SETPRT_64, $ULKPAG_64,
$ULWSET_64
Condition Values Returned
|
SS$_NORMAL
|
The service completed successfully.
|
|
SS$_ACCVIO
|
The
return_va_64 argument or the
return_length_64 argument cannot be written by the
caller.
|
|
SS$_EXPGFLQUOTA
|
The process exceeded its paging file quota.
|
|
SS$_INSFWSL
|
The process's working set limit is not large enough to accommodate the
increased virtual address space.
|
|
SS$_IVACMODE
|
The caller's mode is less privileged than the create mode associated
with the region.
|
|
SS$_IVREGID
|
An invalid region ID was specified.
|
|
SS$_IVVAFLG
|
An invalid flag, a reserved flag, or an invalid combination of flags
and arguments was specified.
|
|
SS$_LEN_NOTPAGMULT
|
The
length_64 argument is not a multiple of CPU-specific
pages.
|
|
SS$_NOSHPTS
|
The region ID of a shared page table region was specified.
|
|
SS$_REGISFULL
|
The specified virtual region is full.
|
$EXTEND
The Extend service increases the amount of space allocated to a disk
file. This service is most useful for extending relative files and
indexed files when you are doing block I/O transfers using the Write
service.
For additional information about this service, see the OpenVMS Record Management Services Reference Manual.
$FAO/$FAOL
Converts a binary value into an ASCII character string in decimal,
hexadecimal, or octal notation; returns the character string in an
output string; and inserts variable character-string data into an
output string.
The Formatted ASCII Output with List Parameter ($FAOL) service provides
an alternate method for specifying input parameters when calling the
$FAO system service.
The formats for both services are shown in the Format section.
On Alpha and Integrity server systems, this service accepts 64-bit
addresses.
Format
SYS$FAO ctrstr ,[outlen] ,outbuf ,[p1]...[pn]
SYS$FAOL ctrstr ,[outlen] ,outbuf ,[prmlst]
C Prototype
int sys$fao (void *ctrstr, unsigned short int *outlen, void
*outbuf,...);
int sys$faol (void *ctrstr, unsigned short int *outlen, void *outbuf,
void *prmlst);
Arguments
ctrstr
| OpenVMS usage: |
char_string |
| type: |
character-coded text string |
| access: |
read only |
| mechanism: |
by 32- or 64-bit descriptor--fixed-length string
descriptor |
Control string passed to $FAO that contains the text to be output
together with one or more $FAO directives. $FAO directives are used to
specify repeat counts or the output field length, or both, and they are
preceded by an exclamation point (!). The ctrstr
argument is the 32- or 64-bit address of a character string descriptor
pointing to the control string. The formatting of the $FAO directives
is described in the Description section.
There is no restriction on the length of the control string or on the
number of $FAO directives it can contain; however, if an exclamation
point must appear in the output string, it must be represented in the
control string by a double exclamation point (!!). A single exclamation
point in the control string indicates to $FAO that the next characters
are to be interpreted as FAO directives.
When $FAO processes the control string, it writes to the output buffer
each character that is not part of an $FAO directive.
If the $FAO directive is valid, $FAO processes it. If the directive
requires a parameter, $FAO processes the next consecutive parameter in
the specified parameter list. If the $FAO directive is not valid, $FAO
terminates and returns a condition value in R0.
Table SYS-35 lists and describes the $FAO directives. Table SYS-36
shows the $FAO output field lengths and their fill characters.
The $FAO service reads parameters from the argument list specified in
the call; these arguments have the names p1,
p2, p3, and so on, up to
p17. Each argument specifies one parameter. Because
$FAO accepts a maximum of 17 parameters in a single call, you must use
$FAOL if the number of parameters exceeds 17. The $FAOL service accepts
any number of parameters used with the prmlst argument.
outlen
| OpenVMS usage: |
word_unsigned |
| type: |
word (unsigned) |
| access: |
write only |
| mechanism: |
by 32- or 64-bit reference |
Length in bytes of the fully formatted output string returned by $FAO.
The outlen argument is the 32- or 64-bit address of a
word containing this value.
outbuf
| OpenVMS usage: |
char_string |
| type: |
character-coded text string |
| access: |
write only |
| mechanism: |
by 32- or 64-bit descriptor--fixed-length string
descriptor |
Output buffer into which $FAO writes the fully formatted output string.
The outbuf argument is the 32- or 64-bit address of a
character string descriptor pointing to the output buffer. The maximum
number of bytes written is limited to 64K.
p1 to pn
| OpenVMS usage: |
varying_arg |
| type: |
quadword (signed) |
| access: |
read only |
| mechanism: |
by value |
$FAO directive parameters. The p1 argument is a
quadword containing the parameter needed by the first $FAO directive
encountered in the control string, the p2 argument is
a quadword containing the parameter needed for the second $FAO
directive, and so on for the remaining arguments up to
p17. If an $FAO directive does not require a
parameter, that $FAO directive is processed without reading a parameter
from the argument list.
Depending on the directive, a parameter can be a value to be converted,
a 32- or 64-bit address of a string to be inserted into the output
string, or a length or argument count. Each directive in the control
string might require a corresponding parameter or parameters.
prmlst
| OpenVMS usage: |
vector_longword_unsigned |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by 32- or 64-bit reference |
List of $FAO directive parameters to be passed to $FAOL. The
prmlst argument is the 32- or 64-bit address of a list
of longwords wherein each longword is a parameter. The $FAOL service
processes these parameters sequentially as it encounters, in the
control string, $FAO directives that require parameters.
The parameter list can be a data structure that already exists in a
program and from which certain values are to be extracted.
Description
The Formatted ASCII Output ($FAO) service converts a binary value into
an ASCII character string in decimal, hexadecimal, or octal notation
and returns the character string in an output string, and inserts
variable character string data into an output string.
The Formatted ASCII Output with List Parameter ($FAOL) service provides
an alternate way to specify input parameters for a call to the $FAO
system service. The formats for both $FAO and $FAOL are shown in the
Format section.
The $FAO_S macro form uses a PUSHL instruction for all parameters
(p1 through p17) passed to the
service; if you specify a symbolic address, it must be preceded with a
number sign (#) or loaded into a register.
You can specify a maximum of 17 parameters on the $FAO macro. If more
than 17 parameters are required, use the $FAOL macro.
This service does not check the length of the argument list and
therefore cannot return the SS$_INSFARG (insufficient arguments) error
status code. If the service does not receive a sufficient number of
arguments (for example, if you omit required commas in the call), you
might not get the desired result.
$FAO Directives
$FAO directives can appear anywhere in the control string. The general
format of an $FAO directive is as follows:
The exclamation point (!) specifies that the following characters are
to be interpreted as an $FAO directive, and the characters DD
represent a 1- or 2-character $FAO directive.
Note
When the characters of the $FAO directive are alphabetic, they must be
uppercase.
|
An $FAO directive can optionally specify the following:
- A repeat count. The format is as follows:
In this case n is a decimal value specifying the number of
times that $FAO is to repeat the directive. If the directive requires a
parameter or parameters, $FAO uses successive parameters from the
parameter list for each repetition of the directive; it does not use
the same parameters for each repetition. The parentheses are required
syntax.
- An output field length. The format is as follows:
In this case m is a decimal value specifying the length of
the field (within the output string) into which $FAO is to write the
output resulting from the directive. The length is expressed as a
number of characters.
- Both a repeat count and output field length. In this case the
format is as follows:
You can specify repeat counts and output field lengths as variables by
using a number sign (#) in place of an absolute numeric value:
- If you specify a number sign for a repeat count, the next
parameter passed to $FAO must contain the count.
- If you specify a number sign for an output field length, the next
parameter must contain the length value.
- If you specify a number sign for both the output field length and
for the repeat count, only one length parameter is required; each
output string will have the specified length.
- If you specify a number sign for the repeat count, the output field
length, or both, the parameters specifying the count, length, or both
must precede other parameters required by the directive.
Numeric FAO output directives (B, W, L, Q, I, A, H, J) can include the
indirect directive @. This immediately precedes the directive (@DD),
and indicates that the next parameter is the address of the value
instead of the value itself. This directive must be used with any
directive that can produce a quadword output when using $FAOL;
otherwise, $FAOL creates a 64-bit sign-extended value. This includes
the Q, A, I, H, and J directives.
- The indirect directive can be used with repeat counts and output
field lengths. In this case the format is as follows:
|
