cgi Format Message ID as HTML

cgiFmtMsgID

The cgiFmtMsgID procedure retrieves a message from the specified message file and formats the message with HTML.

The cgiFmtMsgID procedure prepares a traditional CPF or user-specified message ID for output to a web browser as HTML.

html = cgiFmtMsgID(
 szMsgID         7A    Const 
 szMsgFile      21A    Const OPTIONS(*NOPASS : *OMIT)
 szMsgData     512A    Const OPTIONS(*NOPASS : *OMIT : *VARSIZE)
 nMsgDataLen    10I 0  Const OPTIONS(*NOPASS : *OMIT)
 szRtnHtml   32767A    Const OPTIONS(*NOPASS : *OMIT : *VARSIZE)
 nRtnHtmlLen    10I 0  Const OPTIONS(*NOPASS : *OMIT)
)

Parameters

szMsgID

[input Char(7) const]  This parameter specifies the message ID to be retrieved. A full or partial message ID may be specified. That is a full message ID including the 3-character message prefix, or just the 4-position message ID "number" may be passed. If the message ID is less than 4 position in length, it is padded on the left with zeros.

 

Valid formats for message identifiers are as follows:

 *...v....1

'CFP1006'

'1006'

'CFP0106'

'106'

 

szMsgFile [optional]

[input Char(21) const]  Message file name. This parameter consists of two parts (1) in the first 10 positions, the name of the message file, and (2) in the second 10 positions, the name of the library containing the message file For example:

 

 *...v....1....v....2

'QCPFMSG   QSYS      '

 

An alternative syntax is also supported for the message file name parameter. The alternate syntax allows you to specify the message file name similar to that of an OS/400 CL command, that is it may be qualified using qualified name syntax, as follows:

 *...v....1....v....2

'QSYS/QCPFMSG        '

 

 

szMsgData [optional]

[input Char(512) const]  Specify the message data that will be substituted within the returned message text. If a regular character field (non-data structure) is passes for this parameter, then the 3rd parameter, nMsgDataLength, is not necessary. If a data structure is passes for this parameter, then specify the length of the value passed on the nMsgDataLength parameter.

 

nMsgDataLen  [optional]

[input Int4 (10i0) const]  Specify the length of the message data specified on the 2nd parameter, szMsgData. If the szMsgData parameter is unspecified, or if a regular field or named constant is specified, this parameter may be specified, but is unnecessary as the procedure can determine the length. If a data structure is passed on the szMsgData parameter, then you must pass the length of that data structure (or some other value) on this parameter.  If a data structure is specified, you can use the %SIZE(ds) built-in function to specify the data structure length for this parameter; where "ds" is the name of the data structure being passed. 

 

szRtnHtml [optional]

[input Char(*) ]  Specify a variable to receive the formatted message's generated. This parameter may be any length up to 32k or it may be unspecified. If this parameter is specified and nRtnHtmlLen is not specified, then the this parameter must be large enough to receive the formatted message HTML that is generated.  The HTML returned on this parameter is also returned to the caller as the return value.

 

nRtnHtmlLen  [optional]

[input Int4 (10i0) const]  Specify the length of the return buffer specified on the szRtnHtml parameter. If the szMsgData parameter is unspecified, this parameter is ignored. If this parameter is not specified and szRtnHtml is specified, then the szRtnHtml parameter must be large enough to receive the formatted message HTML that is generated.  

 

Overriding the Message Settings

To override the default message file name being used to extract the messages, use the SetMsgProp (Set message properties) procedure. The default message file name is QCPFMSG on the library list.

Return Value

The return value is the formatted message's HTML. This is the same data returned on the szRtnHtml parameter, but allows the procedure to be called from within an expression, and hence embedding the returned HTML directly into a string..

Example

To format the message information from message ID USR1234 in QUSRMSG as HTML, the following may be used:

     /INCLUDE XTOOLS/QCPYSRC,cgi

.....CSRn01..............OpCode(ex)Extended-factor2++++++++++++++++++++++++++++++++

     C                   Eval      cgiStdOut('<HTML><BODY>'+

     C                               cgiFmtMsgID('USR1234':'QUSRMSG') +

     C                                  '</BODY></HTML>')

In this example, the formatted HTML message is written to the standard-output (stdout) device after wrapping it with conventional HTML tags.