OpenVMS Utility Routines Manual

Document revision date: 19 July 1999

OpenVMS Utility Routines Manual

Contents

Index

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

None.

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

None.

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

None.

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.

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$_DISUSER

SS$_NORMAL

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).

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 Returned

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

None.

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

None.

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.

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

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.

Value of Password_Number Argument	Location
0 or --1	LGI$A_ICR_PWD1
1 or --2	LGI$A_ICR_PWD2
--3	buffer argument

Condition Values Returned

SS$_NORMAL Success.

LGI$_INVPWD Password check failed.

LGI$_NOSUCHUSER No UAF record found.

LGI$ICB_PWDEXPIRED

The LGI$ICB_PWDEXPIRED callback routine checks for password expiration.

Format

LGI$ICB_PWDEXPIRED

RETURNS

No value. Does not return on failure.

Arguments

None.

Description

Use this callback routine to determine whether the account password has expired. If the password is expired, 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

None.

LGI$ICB_USERPARSE

The LGI$ICB_USERPARSE callback routine parses the user name input.

Format

LGI$ICB_USERPARSE input_buffer

RETURNS

OpenVMS usage: cond_value

type: longword (unsigned)

access: write only

mechanism: by value

Condition value in R0.

Argument

input_buffer

OpenVMS usage: character string

type: string descriptor

access: read only

mechanism: by reference

The input buffer must contain the characters LOGIN in the first five character locations, followed by an ASCII space character and then the user name and applicable site-specified qualifiers.

Description

The site can use this callback routine to parse input for interactive logins on character-cell and DECwindows terminals.
Upon completion of this routine, the user name is accessible at the LGI$A_USERNAME entry in the standard arguments vector.

Condition Values Returned

True (1) if successful; otherwise, any condition code returned by CLI$PARSE.

LGI$ICB_USERPROMPT

The LGI$ICB_USERPROMPT callback routine prompts for the user name.

Format

LGI$ICB_USERPROMPT prompt

RETURNS

OpenVMS usage: cond_value

type: longword (unsigned)

access: write only

mechanism: by value

Condition value in R0.

Argument

prompt

OpenVMS usage: character string

type: string descriptor

access: read only

mechanism: by reference

A string that must begin with "cr,lf". For example, to produce the standard user name prompt, use your language equivalent of the following BLISS value:
UPLIT(12,UPLIT BYTE(CR,LF,'Username: '))
Declare the string in C using the following statement:
$DESCRIPTOR(<variable_name>, "lrlnUsername:")
You then pass the descriptor using the variable name.
This routine also produces the standard user name prompt if you pass the value 0 for this argument.

Description

Use this callback routine to interactively prompt for the user name on a character-cell terminal. The callback routine reads the response to the prompt and does standard DCL parsing for the user name and any qualifiers provided. Upon completion of this routine, the user name is accessible at the LGI$A_USERNAME entry in the standard arguments vector.

Condition Values Returned

SS$_NORMAL Success.

LGI$_NOTVALID Retry count exceeded for user input.

LGI$ICB_VALIDATE

The LGI$ICB_VALIDATE callback routine validates the user name and passwords against the system authorization file.

Format

LGI$ICB_VALIDATE username ,pwd1 ,pwd2

RETURNS

OpenVMS usage: cond_value

type: longword (unsigned)

access: write only

mechanism: by value

Condition value in R0.

Arguments

username

OpenVMS usage: character string

type: string descriptor

access: read only

mechanism: by reference

User name.
pwd1

OpenVMS usage: character string

type: string descriptor

access: read only

mechanism: by reference

Primary password.
pwd2

OpenVMS usage: character string

type: string descriptor

access: read only

mechanism: by reference

Secondary password.

Description

The site can use this callback routine to validate the user name and the user's primary and secondary passwords against the system authorization file (SYSUAF.DAT). The routine also:

Updates the user authorization (UAF) record with information about login failures
Performs security auditing
Performs break-in detection and intrusion evasion

Condition Values Returned

Success, or an error indicating the reason for the failure.

Contents

Index

privacy and legal statement

4493PRO_029.HTML

OpenVMS usage:	value
type:	longword (unsigned)
access:	write only
mechanism:	by value

OpenVMS usage:	character string
type:	string descriptor
access:	read only
mechanism:	by reference

OpenVMS usage:	buffer
type:	vector_byte (unsigned)
access:	read only
mechanism:	by reference

OpenVMS usage:	cond_value
type:	longword (unsigned)
access:	write only
mechanism:	by value

OpenVMS usage:	rab
type:	longword (unsigned)
access:	modify
mechanism:	by reference

OpenVMS usage:	mask_longword
type:	longword (unsigned)
access:	read only
mechanism:	by reference

SS$_NORMAL	Success.
LGI$_INVPWD	Password check failed.
LGI$_NOSUCHUSER	No UAF record found.

SS$_NORMAL	Success.
LGI$_NOTVALID	Retry count exceeded for user input.