HP OpenVMS systems documentation

This chapter describes the system declaration mechanism, including LIB$INITIALIZE, which performs calls to any initialization routine declared for the image by the user. However, use of LIB$INITIALIZE is discouraged and should be used only when no other method is suitable. This chapter contains the following sections:

Section 35.1 describes the steps to perform image initialization.

Section 35.2 describes the argument list that is passed from the command interpreter, the debugger, or LIB$INITIALIZE to the main program.

Section 35.3 describes how a library or user program can declare an initialization routine.

Section 35.4 describes how the LIB$INITIALIZE dispatcher calls the initialization routine in a list.

Section 35.5 describes the options available to an initialization routine.

Section 35.6 illustrates with a code example several functions of an initialization routine on VAX, Alpha, and I64 systems.

35.1 Initializing an Image

In most cases, both user and library routines are self-initializing. This means that they can process information with no special action required by the calling program. Initialization is automatic in two situations:

• When the routine's statically allocated data storage is initialized at compile or link time
• When a statically allocated flag is tested and set on each call so that initialization occurs only on the first call

Any special initialization, such as a call to other routines or to system services, can be performed on the first call before the main program is initialized. For example, you can establish a new environment to alter the way errors are handled or the way messages are printed.

Such special initialization is required only rarely; however, when it is required, the caller of the routine does not need to make an explicit initialization call. The run-time library provides a system declaration mechanism that performs all such initialization calls before the main program is called. Thus, special initialization is invisible to later callers of the routine.

On VAX systems, before the main program or main routine is called, a number of system initialization routines are called as specified by a 1-, 2-, or 3-longword initialization list set up by the linker.

On Alpha and I64 systems, before the main program or main routine is called, a number of system initialization routines are called as specified by a 1-, 2-, or 3-quadword initialization list set up by the linker.

On VAX systems, the initialization list consists of the following (in order):

• The addresses of the debugger (if present)
• The LIB$INITIALIZE routine (if present)
• The entry point of the main program or main routine

On Alpha and I64 systems, the initialization list consists of the following (in order):

• The procedure value addresses of the debugger (if present)
• The LIB$INITIALIZE routine (if present)
• The entry point of the main program or main routine

The following initialization steps take place:

1. The image activator maps the user program into the address space of the process and sets up useful information, such as the program name. Then it starts the command language interpreter (CLI).
2. The CLI sets up an argument list and calls the next routine in the initialization list (debugger, LIB$INITIALIZE, main program, or main routine).
3. On VAX systems, the debugger, if present, initializes itself and calls the next routine in the initialization list (LIB$INITIALIZE, main program, or main routine).
   On Alpha and I64 systems, the CLI calls the debugger, if present, to set the initial breakpoints. Then the CLI calls the next entry in the vector.
4. The LIB$INITIALIZE library routine, if present, calls each library and user initialization routine declared using the system LIB$INITIALIZE mechanism. Then it calls the main program or main routine.
5. The main program or main routine executes and, at the user's discretion, accesses its argument list to scan the command or to obtain information about the image. The main program or main routine can then call other routines.
6. Eventually, the main program or main routine terminates by executing a return instruction (RET) with R0 set to a standard completion code to indicate success or failure, where bit <0> equals 1 (success) or 0 (failure).
   The MACRO compiler maps the registers in Macro-32 source programs to I64 registers on your behalf, as shown in Table 18-16, to minimize source changes. This allows existing programs to use R0 and have the generated code return the value in R8 as prescribed by the calling standard.
7. The completion code is returned to LIB$INITIALIZE (if present), the debugger (if present), and, finally, to the CLI, which issues a SYS$EXIT system service with the completion status as an argument. Any declared exit handlers are called at this point.

Figure 35-1 and Figure 35-2 illustrate the sequence of calls and returns in a typical image initialization. Each box is a routine activation as represented on the image stack. The top of the stack is at the top of the figure. Each upward arrow represents the result of a call instruction that creates a routine activation on the stack to which control is being transferred. Each downward arrow represents the result of a RET (return) instruction. A RET instruction removes the routine activation from the stack and causes control to be transferred downward to the next box.

A user program can alter the image initialization sequence by making a program section (PSECT) contribution to PSECT LIB$INITIALIZE and by declaring EXTERNAL LIB$INITIALIZE. This adds the optional initialization steps shown in Figure 35-1 and Figure 35-2 labeled "Program Section Contribution to LIB$INITIALIZE." (A program section is a portion of a program with a given protection and set of storage management attributes. Program sections that have the same attributes are gathered together by the linker to form an image section.) If the initialization routine also performs a coroutine call back to LIB$INITIALIZE, the optional steps labeled "Coroutine Call Back to LIB$INITIALIZE" in Figure 35-1 and Figure 35-2 are added to the image initialization sequence.

On VAX systems, Figure 35-1 shows the call instruction calling the debugger, if present, and the debugger then directly calling LIB$INITIALIZE and the main program.

Figure 35-1 Sequence of Events During Image Initialization on VAX Systems

On Alpha and I64 systems, Figure 35-2 shows the call instruction calling the debugger, if present, to set a breakpoint at the main program's entry point.

Figure 35-2 Sequence of Events During Image Initialization on Alpha and I64 Systems

The following argument list is passed from the CLI, the debugger, or LIB$INITIALIZE to the main program. This argument list is the same for each routine activation.

(start ,cli-coroutine [,image-info])

The start argument is the address of the entry in the initialization vector that is used to perform the call.

The cli-coroutine argument is the address of a CLI coroutine to obtain command arguments. For more information, see the OpenVMS Utility Routines Manual.

The image-info argument is useful image information, such as the program name.

The debugger or LIB$INITIALIZE, or both, can call the next routine in the initialization chain using the following coding sequence:

. . . ADDL #4, 4(AP) ; Step to next initialization list entry MOVL @4(AP), R0 ; R0 = next address to call CALLG (AP), (R0) ; Call next initialization routine . . .

This coding sequence modifies the contents of an argument list entry. Thus, the sequence does not follow the OpenVMS calling standard. However, the argument list can be expanded in the future without requiring any change either to the debugger or to LIB$INITIALIZE.

35.3 Declaring Initialization Routines

Any library or user program module can declare an initialization routine. This routine is called when the image is started. The declaration is made by making a contribution to the LIB$INITIALIZE program section, which contains a list of routine entry point addresses to be called before the main program or main routine is called.

The following example declares an initialization routine by placing the routine entry address INIT_PROC in the list:

.EXTRN LIB$INITIALIZE ; Cause library initialization ; Dispatcher to be loaded .PSECT LIB$INITIALIZE, NOPIC, USR, CON, REL, GBL, NOSHR, NOEXE, RD, NOWRT, LONG .LONG INIT_PROC ; Contribute entry point address of ; initialization routine. .PSECT ...

The .EXTRN declaration links the initialization routine dispatcher, LIB$INITIALIZE, into your program's image. The reference contains a definition of the special global symbol LIB$INITIALIZE, which is the routine entry point address of the dispatcher. The linker stores the value of this special global symbol in the initialization list along with the starting address of the debugger and the main program. The GBL specification ensures that the PSECT LIB$INITIALIZE contribution is not affected by any clustering performed by the linker.

Note that moving modules and PSECTS around to affect symbol resolution may result in unintended memory placement within your image. If, for example, you add a CLUSTER statement to your linker options file, the initialization code may not run because the CLUSTER statement in the linker option file may cause the various LIB$INITIALIZE PSECTS to become separated. To remedy this possible condition, either add to your options file a CLUSTER or COLLECT statement like the following:

CLUSTER = <cluster name>,,,<module>, SYS$LIBRARY:STARLET.OLB/include = LIB$INITIALIZE COLLECT = <cluster name>, LIB$INITIALIZDZ, LIB$INITIALIZD_, LIB$INITIALIZE,LIB$INITIALIZE$

35.4 Dispatching to Initialization Routines

The LIB$INITIALIZE dispatcher calls each initialization routine in the list with the following argument list:

CALL init-proc (init-coroutine ,cli-coroutine [, image-info])

The init-coroutine argument is the address of a library coroutine to be called to effect a coroutine linkage with LIB$INITIALIZE.

The cli-coroutine is the address of a CLI coroutine used to obtain command arguments.

The image-info argument is useful image information, such as the program name.

35.5 Initialization Routine Options

An initialization routine can be used to do the following:

• Set up an exit handler by calling the Declare Exit Handler ($DCLEXH) system service, although exit handlers are generally set up by using a statically allocated first-time flag.
• Initialize statically allocated storage, although this is done preferably at image activation time using compile-time and link-time data initialization declarations or by using a first-time call flag in its statically allocated storage.
• Call the initialization dispatcher (instead of returning to it) by calling the init-coroutine argument. This achieves a coroutine link. Control returns to the initialization routine when the main program returns control. Then the initialization routine should also return control to pass back the completion code returned by the main program (to the debugger or CLI, or both).
• Establish a condition handler in the current frame before performing the preceding actions. This leaves the initialization routine condition handler on the image stack for the duration of the image execution. This occurs after the CLI sets up the catchall stack frame handler and after the debugger sets up its stack frame handler. Thus, the initialization routine handler can override either of these handlers, because it will receive signals before they do.

The following code fragment, which works on VAX, Alpha, and I64 systems, shows how an initialization routine does the following:

• Establishes a handler
• Calls the init-coroutine argument routine, so that the coroutine calls the initialization dispatcher
• Gains control after the main program returns
• Returns to the normal exit processing

.ENTRY INIT_PROC, ^M<> ; No registers used MOVAL HANDLER, (FP) ; Establish handler ... ; Perform any other initialization CALLG (AP), @INIT_CO_ROUTINE(AP) ; Continue initialization which 10$: ; then calls main program or ; routine. ... ; Return here when main program ; returns with R0 = completion RET ; Status return to normal exit ; processing with R0 = completion ; status .ENTRY HANDLER, ^M<...> ; Register mask ... ; handle condition ; could unwind to 10$ MOVL #..., R0 ; Set completion status with a ; condition value RET ; Resignal or continue depending ; on R0 being SS$_RESIGNAL or ; SS$_CONTINUE.

• Macros used in 64-bit programming
• Examples of 64-bit programming
• Generic macros used for calling system services
• OpenVMS data types
• Distributed name services on OpenVMS VAX

ACM: Authentication and Credential Management.

ACM client process: A process that calls the SYS$ACM[W] system service.

ACM client program: A program that calls the SYS$ACM[W] system service.

ACM communications buffer: A protected area provided by the SYS$ACM[W] system service by the ACM context argument containing an itemset to specify required user interaction when using dialogue mode.

ACM context argument: An argument to the SYS$ACM[W] system service that passes a pointer variable. If the SYS$ACM[W] system service requires additional information in dialogue mode, it will fill in that variable so it points to an ACM communications buffer.

ACME: Authentication and Credential Management Extension.

ACME agent: ACME agent shareable image.

ACME agent shareable image: A shareable image used within the ACME server process to implement one or more forms of authentication and optionally provide credentials to the process that called the SYS$ACM[W] system service. The VMS ACME is an example of an ACME agent shareable image that ships with the OpenVMS operating system.

ACME server process: A detached process that performs backend operations in support of the SYS$ACM[W] system service. It is sometimes refered to as the ACM Dispatcher.

ACME status: The fourth longword returned in the structure to which the ACMSB argument to the SYS$ACM[W] system service points. The symbolic name of this cell is ACMESB$L_ACME_STATUS. The ACME status contains a status encoded in a format specific to a particular ACME agent unless the primary status contains one of the following values:

• SS$_BADITMCOD
• SS$_BADBUFLEN
• SS$_BADPARAM

When the primary status contains one of those values, the ACME status indicates what item code was in error.

authentication policy: A set of rules determining how users are authenticated on a system. A system can have different authentication policies defined at the same time.

credentials: A set of items used to represent the user's security profile attributes for a particular DOI. The SYS$ACM[W] system service returns credentials to the ACM client program as an attachment to a persona in the form of a persona extension.

deferred confirmation: A pattern of dialogue mode operation in which an ACM client program confirms a no-echo prompt (such as for a new password) only after the initial response has been at least partially qualified by an ACME agent. This presents a more hospital interface to users than immediate confirmation.

designated DOI: The Domain of Interpretation (DOI) chosen to prevail in processing a particular Authenticate Principal or Change Password request. Interactiion between the various ACME agents on a system, in accordance with policy controls set by the system manager, leads to one of the ACME agents becoming the designated DOI. Other DOIs may contribute to authentication and may provide credentials. When the call to the SYS$ACM[W] system service specifies a target DOI, that DOI becomes the designated DOI.

dialogue mode: A form of operation whereby the ACM client program calls the SYS$ACM[W] system service successively to complete a full Authenticate Principal or Change Password operation. You specify dialogue mode by providing the context argument when calling the SYS$ACM[W] system service.

DOI: A Domain of Interpretation is an authentication policy implemented by an ACME agent shareable image or by several in combination. In addition, a DOI defines the set of credentials that represents a user in its security environment.

event: Information an ACM client program transmits to an ACME agent for use in some fashion specific to a particular DOI. It might be recorded in a log or used to trigger some mode of operation. Requirements for sending an event, including any required privilege, are specific to the DOI.

immediate confirmation: A pattern of dialogue mode operation in which an ACM client program confirms a no-echo prompt (such as for a new password) before returning the initial response to the ACME server process (and thus before any qualification of the new password regarding acceptability). This presents a lighter system load than deferred confirmation.

item list: A chain of item list segments, with each segment terminated by the item ACME$_CHAIN except for the final segment, which is terminated by a zero item. Each ACME$_CHAIN item points to the successor segment.

item list segment: An array of standard VMS item_list_3 or item list entry B descriptors.

itemset: An array of itemset entries provided by the SYS$ACM[W] system service within its ACM communications buffer to specify required user interaction.

itemset entry: An element within an itemset describing a single user interaction request from an ACME agent.

LGI callout: A mechanism introduced in OpenVMS Version 5.5 for customizing LOGINOUT interaction. This was the predecessor to the ACME mechanism.

login type: Also known as login class. One of the five types of authentication supported by the SYS$ACM[W] system service (local, dialup, remote, network, and batch).

nondialogue mode: Nondialogue mode is a form of operation whereby the ACM client program calls the SYS$ACM[W] system service once with all items required. You can specify that your call to the SYS$ACM[W] system service is to be handled in nondialogue mode by not providing any ACM context argument when calling the SYS$ACM[W] system service.

persona: A kernel data structure (PSB) associated with a process forming the basis for identity within the operating system.

persona extension: A kernel data structure (PSB) attached to a persona associated with a process for the purpose of holding credentials for a particular DOI.

persona ID: A longword value representing a persona held by a particular process.

primary status: The first longword returned in the structure to which the ACMSB argument to the SYS$ACM[W] system service points. The symbolic name of this cell is ACMESB$L_STATUS. It indicates the overall status of the request.

principal name: The initial name used to claim an identity, expressed in a syntax appropriate for a particular DOI. Note that the traditional input prompt Username: is actually requesting a principal name be entered. In simple cases, the spelling of the principal name is the same as the spelling of the VMS user name to which it maps.

principal name mapping: The transformation performed by an ACME agent that determines what VMS use name is associated with a particular principal name.

message category: The code value indicating the purpose of output dialogue text.

request: The collection of data within the ACME server process pertaining to a particular call or related set of calls to the SYS$ACM[W] system service by a client process.

return status: The value returned by the SYS$ACM[W] system service. Success indicates only that the request was sent to the ACME server process. Success does not indicate the final result of processing.

secondary status: The second longword returned in the structure to which the ACMSB argument to the SYS$ACM[W] system service points. The symbolic name of this cell is ACMESB$L_SECONDARY_STATUS. It indicates a more detailed explanation of the primary status.

status ACME ID: The third longword returned in the structure to which the ACMSB argument to the SYS$ACM[W] system service points. The symbolic name of this cell is ACMESB$L_ACME_ID. It indicates the identity of the ACME agent that provided status information.

SYS$ACM[W] system service: The Authenication and Credential Management system service.

target DOI: The DOI specified on the initial call to the SYS$ACM[W] system service to be the one to handle the request.

targeted request: A request where the caller of the SYS$ACM[W] system service specifies item code ACME$_TARGET_DOI_ID or item code ACME$_TARGET_DOI_NAME to indicate which DOI should handle the request.

TCB: Trusted Computing Base. The set of components on a system that must be trusted for secure operation of the system.

UCS encoding: Unicode Character Set encoding. This uses the character set under which characters are represented in 16 bits. OpenVMS uses UCS2-4, in which each 16-bit character is stored in a 32-bit cell (4 bytes).

VMS ACME: The ACME agent that implements the traditional OpenVMS authentication policy.

VMS user name: The name used to identify a user to the OpenVMS operating system after a user is logged in. It is case-blind and limited to 12 alphanumeric characters making it considerable less flexible than the principal name.

well-known item: The seven common input text items that might be requested by any ACME agent: ACME$_PASSWORD_SYSTEM, ACME$_PRINCIPAL_NAME, ACME$_PASSWORD_1, ACME$_PASSWORD_2, ACME$_NEW_PASSWORD_SYSTEM, ACME$_NEW_PASSWORD_1, or ACME$_NEW_PASSWORD_2.