 |
OpenVMS Utility Routines Manual
LGI$ICR_INIT
The LGI$ICR_INIT callout routine may perform any required
initialization functions.
Format
LGI$ICR_INIT arg_vector ,context
RETURNS
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
Returns status indicating whether and how to proceed with the login.
Arguments
arg_vector
| OpenVMS usage: |
vector |
| type: |
vector_longword_unsigned |
| access: |
modify |
| mechanism: |
by reference |
Vector containing callbacks and login information.
context
| OpenVMS usage: |
context |
| type: |
longword (unsigned) |
| access: |
modify |
| mechanism: |
by reference |
Pointer to site's local context.
Description
This routine is called for all job types before opening input and
output files. If desired, the callout routine may initialize the
context argument, which LOGINOUT subsequently passes
to each callout routine with the address of local storage specific to
the callout image.
Typical Condition Values
|
SS$_NORMAL
|
Access permitted; continue policy checks.
|
|
LGI$_SKIPRELATED
|
Access permitted; omit calls to the LGI$ICR_INIT callout routine in
subsequent images.
|
|
Other
|
Disallow the login.
|
Associated OpenVMS Policy Function
LGI$ICR_JOBSTEP
The LGI$ICR_JOBSTEP callout routine signals the start of each batch job
step.
Format
LGI$ICR_JOBSTEP input_file_name ,context ,write_fao
RETURNS
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
Not applicable.
Arguments
input_file_name
| OpenVMS usage: |
descriptor |
| type: |
character string |
| access: |
read |
| mechanism: |
by reference |
The name of the input file.
context
| OpenVMS usage: |
context |
| type: |
longword (unsigned) |
| access: |
modify |
| mechanism: |
by reference |
Pointer to site's local context.
write_fao (fao_string[,arg1[,arg2][,...]]])
| OpenVMS usage: |
routine |
| type: |
procedure |
| access: |
read |
| mechanism: |
by reference |
Address of a routine that may be called to format and display output.
The routine has fao_string as its first argument,
followed by a variable number of arguments. (See the $FAO system
directive in the OpenVMS System Services Reference Manual for more information.)
Description
The LGI$ICR_JOBSTEP routine alerts the site of each job step in a batch
job. The routine is invoked as LOGINOUT processes each job step. For
the first job step, the LGI$ICR_JOBSTEP callout routine is invoked
immediately following the LGI$ICR_IDENTIFY callout routine. For all
other job steps, it is the only callout routine that is invoked.
The routine is provided with the input file name, but the input file is
not open when the routine is called. For the first job step, the
LGI$ICR_INIT callout routine may provide the batch job step routine
with context. For other job steps, the context
argument is a null.
For all job steps except the first, the output file is open, and the
routine specified by the write_fao argument is
available.
There is no OpenVMS policy associated with LGI$ICR_JOBSTEP.
Typical Condition Values
|
LGI$_SKIPRELATED or any error value
|
Access permitted; omit calls to the LGI$ICR_JOBSTEP callout routine in
subsequent images.
|
Associated OpenVMS Policy Function
LGI$ICR_LOGOUT
The LGI$ICR_LOGOUT callout routine permits the site callout images to
respond to the DCL command LOGOUT.
Note
This routine is not called if the calling process is deleted with
STOP/PROCESS ($DELPRC). If the calling terminal is disconnected when
logout occurs, this routine must not produce output.
|
Format
LGI$ICR_LOGOUT username ,processname ,creprc_flags ,write_fao
RETURNS
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
Returns logout status from the site program.
Arguments
username
| OpenVMS usage: |
descriptor |
| type: |
character string |
| access: |
read |
| mechanism: |
by reference |
User name.
processname
| OpenVMS usage: |
descriptor |
| type: |
character string |
| access: |
read |
| mechanism: |
by reference |
Process name.
creprc_flags
| OpenVMS usage: |
mask_longword |
| type: |
longword_unsigned |
| access: |
read |
| mechanism: |
by reference |
Process creation status flags.
write_fao (fao_string[,arg1[,arg2][,...]]])
| OpenVMS usage: |
routine |
| type: |
procedure |
| access: |
read |
| mechanism: |
by reference |
Procedure for writing data. The value is 0 if output is not permitted.
Address of a routine that may be called to format and display output.
The routine has fao_string as its first argument,
followed by a variable number of arguments. (See the $FAO system
directive in the OpenVMS System Services Reference Manual for more information.)
Description
The LGI$ICR_LOGOUT routine is invoked after auditing is completed and
immediately before LOGOUT prints the logout message. This routine
cannot prevent the logout from finishing, but it may prevent display of
the standard logout message.
Typical Condition Values
|
LGI$_SKIPRELATED or any error value
|
Access permitted; omit calls to the LGI$ICR_LOGOUT callout routine in
subsequent images.
|
Associated OpenVMS Policy Function
13.5 LOGINOUT Callback Routines
LOGINOUT callout routines use callback routines to interact with the
user or to access other LOGINOUT services. This section describes the
individual callback routines. The description of each routine includes
the following:
- The format of the call command
- The anticipated information returned by the called routine
- The arguments presented to the called routine
- A general description of the routine
- Condition values that indicate the return status of the routine,
success or failure
LGI$ICB_ACCTEXPIRED
The LGI$ICB_ACCTEXPIRED callback routine checks for account expiration.
Format
LGI$ICB_ACCTEXPIRED
RETURNS
No value. Does not return on failure.
Arguments
None.
Description
The site can use this callback routine to determine if the specified
account is expired. If the account is expired, the LGI$ICB_ACCTEXPIRED
callback routine:
- Writes its standard error message to the user terminal, if a
terminal exists
- Does not return control to the caller
Condition Values Returned
LGI$ICB_AUTOLOGIN
The site may use the LGI$ICB_AUTOLOGIN callback routine to determine
whether the standard OpenVMS autologin functionality applies for this
terminal.
Format
LGI$ICB_AUTOLOGIN
RETURNS
| OpenVMS usage: |
value |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
True (logical 1) if autologin enabled; 0 otherwise.
Arguments
None.
Description
If the standard OpenVMS autologin functionality applies, the callback
routine returns the user name to the site program using the standard
argument vector so that the autologin process may continue.
The autologin determination is made before the site prompts
for the user passwords. The callback routine is applicable only for
interactive character-cell logins.
Note
Standard OpenVMS policy uses autologin only on directly connected or
LAT connected character-cell terminals. The LGI$ICB_AUTOLOGIN callback
routine checks the automatic login file (ALF) SYS$SYSTEM:SYSALF.DAT to
make the determination.
A DECwindows callout can include a method for doing a DECwindows
autologin. In that case, the callout routine should set the autologin
flag to true before returning control to LOGINOUT.
|
Condition Values Returned
LGI$ICB_CHECK_PASS
The LGI$ICB_CHECK_PASS callback routine checks a password against the
user authorization file (UAF) record.
Format
LGI$ICB_CHECK_PASS password ,uaf_record ,pwd_number
RETURNS
| OpenVMS usage: |
value |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
The value 1 for a valid password. The value --4 for an invalid password.
Arguments
password
| OpenVMS usage: |
character string |
| type: |
string descriptor |
| access: |
read only |
| mechanism: |
by reference |
User-supplied password to be validated.
uaf_record
| OpenVMS usage: |
buffer |
| type: |
vector_byte (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
Address of buffer containing UAF record.
pwd_number
| OpenVMS usage: |
value |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
Password number, 0 (primary) or 1 (secondary).
Description
The site uses this callback routine to check the user-supplied password
against the UAF record provided as the second argument. If the password
is valid, the routine returns a 1 in R0; if the password is invalid,
the routine returns a --4 in R0.
Condition Values Returned
LGI$ICB_DISUSER
The LGI$ICB_DISUSER callback routine checks the disabled user account
flag.
Format
LGI$ICB_DISUSER action
RETURNS
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
Condition value in R0.
Argument
action
| OpenVMS usage: |
value |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
This argument can take two values:
| If Value of Action Is... |
Then... |
|
LGI$_DISUSER_STOP
|
Do not return on error.
|
|
LGI$_DISUSER_RETURN
|
Return LGI$_DISUSER or SS$_NORMAL.
|
Description
The site can use this callback routine to establish the standard
OpenVMS action if the DISUSER flag is set.
Condition Values Returned
LGI$ICB_GET_INPUT
The LGI$ICB_GET_INPUT callback routine enables interaction with the
user.
Format
LGI$ICB_GET_INPUT rab ,flags
RETURNS
No value. Does not return on failure.
Arguments
rab
| OpenVMS usage: |
rab |
| type: |
longword (unsigned) |
| access: |
modify |
| mechanism: |
by reference |
Data structure used to set up a read-with-prompt OpenVMS RMS operation.
Normally you pass the RAB address in LGI$A_ICR_INPUT_RAB.
flags
| OpenVMS usage: |
mask_longword |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
A data structure that determines the error response as follows:
| Flags Value |
Response |
|
0
|
Normal error message.
|
|
1
|
LOGINOUT exits quietly.
|
|
2
|
Normal error message; however, the callback routine returns control to
the caller rather than exiting on timeout (timeout status is in RAB).
|
Description
The LGI$ICB_GET_INPUT callback routine invokes the LOGINOUT input
routine to enable interaction with character-cell terminal users. The
read operation provides a timeout to ensure that the UAF record does
not remain locked if the user presses Ctrl/S.
Condition Values Returned1
No return value. Examine status in RAB to determine the results of the
read operation.
LGI$ICB_GET_SYSPWD
The LGI$ICB_GET_SYSPWD callback routine validates the system password.
Format
LGI$ICB_GET_SYSPWD
RETURNS
No value. Does not return on failure.
Arguments
None.
Description
This callback routine performs standard system password-checking for
interactive logins on character-cell terminals only.
If the system password is validated, this callback routine returns
control to the caller. If the system password is not validated, the
LOGINOUT image exits, and the login is terminated.
Condition Values Returned
LGI$ICB_MODALHOURS
The LGI$ICB_MODALHOURS callback routine checks for restrictions on
access modes and access hours.
Format
LGI$ICB_MODALHOURS
RETURNS
No value. Does not return on failure.
Arguments
None.
Description
The site uses this callback routine to establish the access modes and
access hours available to the user. If the user is not authorized to
access the system from this login class (batch, dialup, local, remote,
network) at this time (as specified in the UAF), the callback routine:
- Writes its standard error message to the user terminal, if there is
a terminal
- Does not return control to the caller
Condition Values Returned
LGI$ICB_PASSWORD
The LGI$ICB_PASSWORD callback routine produces the specified password
prompt and then processes the input.
Format
LGI$ICB_PASSWORD password_number ,prompt ,buffer
RETURNS
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
Condition value in R0.
Arguments
password_number
| OpenVMS usage: |
value |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
A numeric value indicating which password to prompt for and what action
to take on it:
| Value |
Prompt for |
|
0
|
Primary password and validate it
|
|
1
|
Secondary password and validate it
|
|
--1
|
Primary password but do not validate it
|
|
--2
|
Secondary password but do not validate it
|
|
--3
|
Arbitrary 32-character value returned to buffer specified in
buffer
|
If the value is --3, you must specify the prompt
argument and the buffer argument.
prompt
| OpenVMS usage: |
character string |
| type: |
string descriptor |
| access: |
read only |
| mechanism: |
by reference |
String that must begin with "cr,lf". If this argument is not
supplied, the standard prompt is used.
buffer
| OpenVMS usage: |
character string |
| type: |
string descriptor |
| access: |
modify |
| mechanism: |
by reference |
Buffer having at least 32 bytes available to store password when
password_number argument value is --3.
Description
The site can use this callback routine to interactively prompt for
passwords. The routine uses either the standard OpenVMS password prompt
or a prompt provided by the caller in the second argument.
The password is returned in one of the following locations, depending
on the value of the password_number argument:
| Value of Password_Number Argument |
Location |
|
0 or --1
|
LGI$A_ICR_PWD1
|
|
1 or --2
|
LGI$A_ICR_PWD2
|
|
--3
|
buffer argument
|
Note
This routine will do overstriking, if necessary, to support echo local
terminals. See the OpenVMS Programming Concepts Manual for more information about echo
terminals.
|
Condition Values Returned
|
SS$_NORMAL
|
Success.
|
|
LGI$_INVPWD
|
Password check failed.
|
|
LGI$_NOSUCHUSER
|
No UAF record found.
|
|
