Generate Alert (QALGENA) API

The Generate Alert (QALGENA) API, an alert API, creates an alert for a particular message ID. The alert is then returned to the calling program.

Authorities and Locks

Alert Table Authority

*USE

Message File Authority

*READ

Library Authority

*USE

Required Parameter Group

Receiver variable (alert major vector)

OUTPUT; CHAR(*)

The variable that receives the generated alert, in the format of an SNA alert major vector. This area must be large enough to hold the alert. If the area is too small, the alert is not returned. A suggested size is 512 bytes because alerts cannot exceed 512 bytes for the i5/OS licensed program.

Length of receiver variable

INPUT; BINARY(4)

The length of the receiver variable parameter. If this is too small, no data is returned, and the API ends with an exception.

Size of alert

OUTPUT; BINARY(4)

The size of the successfully generated alerts. If the size of the alert is smaller than the length of receiver variable, the alert is returned in the receiver variable. If the size of the alert is greater than the length of receiver variable, the alert is not returned.

Qualified alert table (message file) name

INPUT; CHAR(20)

The name of the alert table where the alert description defining the alert is stored, and the name of the library in which it resides. This parameter also identifies the name of the message file to use because the alert table and message file must have the same name.

The first 10 characters contain the alert table name, and the second 10 characters contain the name of the library.

Valid values for the library name are:

*CURLIB	The job's current library. The alert table and message file must both be in this library.
*LIBL	The library list. The alert table and message file can be in different libraries, but the libraries must both be in the library list.
Specific library	The alert table and message file must be in the same library.

Message ID

INPUT; CHAR(7)

The message ID of the alert description defining the alert. This parameter also identifies the message ID of the corresponding message description. The message does not need to be an alertable message. The ALROPT parameter of the Display Message Description (DSPMSGD) command is ignored and an alert is always returned, provided that an alert description with the given message ID exists in the given alert table.

Message data

INPUT; CHAR(*)

The message data to use for message substitution on the alert description and message description. The format of the message data is the same as used for the Send Program Message (SNDPGMMSG) command and the Send Program Message (QMHSNDPM) API. See the CL Programming topic for more information about message data in general and the online help for details about the SNDPGMMSG command.

Length of message data

INPUT; BINARY(4)

The length of the message data provided by the message data parameter above.

Error code

I/O; CHAR(*)

The structure in which to return error information. For the format of the structure, see Error Code Parameter.

Error Handling

Some of the QALGENA API errors allow an alert to be returned to the application. An alert is returned to the application in these cases:

• The user is not authorized to the message file.
• A message cannot be added to the alert because the message or message file cannot be found.

No alert is returned to the application in these cases:

• The user is not authorized to the alert table.
  
  
• i5/OS alert support cannot build an alert because no message ID is given, the alert table is missing or damaged, or no alert description is found. In this case, the alert generated could only be a cause-undetermined alert of little or no value.

Error Messages