---

This call establishes a log-in connection to VC/m. It performs two basic functions:

• Validation of the user ID
• Reservation of a license slot

While connected, a user license slot is in use by the calling program.

It is not mandatory for a connection to be made before making a call to any VC/m API function. However, if a call is made but no free license slots are available, the call will fail with an error message. It is therefore recommended that a connection is established before any other API calls are made.

If a VC/m API call is made from within VC/m (i.e. through a custom menu function), it is not necessary to establish a connection since logging into VC/m will have done this.

The userid argument which is required by all API calls is available in the %usr variable. This variable can be used to avoid the overhead of repeatedly deriving the user ID from the host operating system.

This callout is called when a change request is updated. It must be written as an extrinsic function.

Usage:

set ok=$$connect^%vcapi(.userid,.license,.err)

Inputs:

userid

VC/m user ID (derived from host operating system if null)

Outputs:

$$connect	1 = Operation succeeded 0 = Operation failed
userid	User ID as supplied or derived from host operating system
license	License token (used to disconnect)
err	Error message if operation failed

Error messages:

vc0001 - Invalid user	The user ID is not registered with VC/m.
vc0002 - Number of licensed users is nn. License limit is exceeded.	The number of users connected to VC/m at the time of the call has exceeded the license limit for this instance of VC/m.
vc0003 - Invalid user	The user ID cannot be derived from the host operating system and must be supplied by the calling function.
vc0004 - VC/m is not installed or not licensed	The license key file was not found, could not be opened or is invalid.
vc0005 - The license for VC/m expired on dd-mmm-ccyy	The license key is time limited and has now expired.