![[OpenVMS documentation]](../../images/openvms_doc_banner_top.gif)
|
![[Site home]](../../images/buttons/bn_site_home_off.gif)
![[Send comments]](../../images/buttons/bn_comments_off.gif)
![[Help with this site]](../../images/buttons/bn_site_help_off.gif)
![[How to order documentation]](../../images/buttons/bn_order_docs_off.gif)
![[OpenVMS site]](../../images/buttons/bn_openvms_off.gif)
![[Compaq site]](../../images/buttons/bn_compaq_off.gif)
|
| Updated: 11 December 1998 |
|
|
|
|
| Updated: 11 December 1998 |
OpenVMS System Services Reference Manual
| Previous | Contents | Index |
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.
SYS$EXPREG pagcnt ,[retadr] ,[acmode] ,[region]
int sys$expreg (unsigned int pagcnt, struct _va_range *retadr, unsigned int acmode, char region);
pagcnt
OpenVMS usage: longword_unsigned type: longword (unsigned) access: read only mechanism: by value
Number of pages (on VAX systems) or pagelets (on Alpha systems) to add to the current end of the program or control region. The pagcnt argument is a longword value containing this number.On Alpha 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.
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.
None
The process's paging file quota (PGFLQUOTA) must be sufficient to accommodate the increased size of the virtual address space.
$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.
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. 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.
On Alpha 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.
SYS$EXPREG_64 region_id_64 ,length_64 ,acmode ,flags ,return_va_64 ,return_length_64
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);
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 Compaq 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.
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.
None
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.
$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
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.
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 systems, this service accepts 64-bit addresses.
SYS$FAO ctrstr ,[outlen] ,outbuf ,[p1]...[pn]
SYS$FAOL ctrstr ,[outlen] ,outbuf ,[prmlst]
int sys$fao (void *ctrstr, unsigned short int *outlen, void *outbuf,...);
int sys$faol (void *ctrstr, unsigned short int *outlen, void *outbuf, void *prmlst);
ctrstr
OpenVMS usage: char_string type: character-coded text string access: read only mechanism: by 32- or 64-bit descriptor--fixed-length string descriptor (Alpha) mechanism: by 32-bit descriptor--fixed-length string descriptor (VAX)
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 (on Alpha systems) or the 32-bit address (on VAX systems) 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-9 lists and describes the $FAO directives. Table SYS-10 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 (Alpha) mechanism: by 32-bit reference (VAX)
Length in bytes of the fully formatted output string returned by $FAO. The outlen argument is the 32- or 64-bit address (on Alpha systems) or the 32-bit address (on VAX systems) 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 (Alpha) mechanism: by 32-bit descriptor--fixed-length string descriptor (VAX)
Output buffer into which $FAO writes the fully formatted output string. The outbuf argument is the 32- or 64-bit address (on Alpha systems) or the 32-bit address (on VAX systems) 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 (Alpha) mechanism: by 32-bit reference (VAX)
List of $FAO directive parameters to be passed to $FAOL. The prmlst argument is the 32- or 64-bit address (on Alpha systems) or the 32-bit address (on VAX systems) 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.
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 can appear anywhere in the control string. The general format of an $FAO directive is as follows:
!DD
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:
!n(DD)
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:
!mDD
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:
!n(mDD)
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:
!n(m@DD)
To ensure that addresses and integers are displayed properly on the system, use the following conventions when using the $FAO and $FAOL system services:
- Identify longword data as !xL (where x is O, X, Z, U, or S).
- On Alpha systems, identify quadword data as !xQ for $FAO and $FAOL_64 or !@xQ for $FAOL (where x is O, X, Z, U, or S). Omitting the indirect directive for $FAOL can result in a 64-bit sign-extended value being created.
- If the size of an address is determined by operating system software (32 bits on VAX and 64-bits on Alpha systems), identify the address as !xA for $FAO and $FAOL_64 or !@xA for $FAOL (where x is O, X, Z, U, or S).
- If the size of an address is determined by the hardware architecture (32 bits on VAX, but 64 bits on Alpha, identify the address as !xH for $FAO and $FAOL_64 or !@xH for $FAOL (where x is O, X, Z, U, or S). Omitting the indirect directive for $FAOL can result in a 64-bit sign-extended value being created.
- If the size of an integer is determined by operating system software (32 bits on both VAX and Alpha systems), identify the integer as !xI for $FAO and $FAOL_64 or !@xI for $FAOL (where x is O, X, Z, U, or S).
- If the size of an integer is determined by the hardware architecture (32 bits on VAX, but 64 bits on Alpha), identify the address as !xJ for $FAO and $FAOL_64 or !@xJ for $FAOL (where x is O, X, Z, U, or S). Omitting the indirect directive for $FAOL can result in a 64-bit sign-extended value being created.
Previous Next Contents Index
![[OpenVMS documentation]](../../images/openvms_doc_banner_bottom.gif)
Copyright © Compaq Computer Corporation 1998. All rights reserved.
Legal4527PRO_035.HTML