Forms Information Management
Forms information management tasks retrieve online form definitions and contents. Serena XML supports the following tasks for general use:
-
List Global Online Forms - FORMS GBL LIST
-
List Package Online Forms - FORMS PKG LIST
-
List Package Online Form Details - FORMS PKG DETAIL
List Global Online Forms - FORMS GBL LIST
The global forms list function retrieves global form definitions previously created using online forms maintenance. Included in the returned definition are a global description of the form, approver and notification information, and a variable list defined by the customer during forms maintenance.
The Serena XML service/scope/message tags for a message to list the global form definitions are:
<service name="FORMS">
<scope name="GBL">
<message name="LIST">
These tags appear in both requests and replies.
FORMS GBL LIST — Requests
The global online forms list supports two kinds of requests:
-
Complete Forms List — Use the "match-all" (asterisk) wildcard in the <formNumber> tag to request information about all globally defined online forms.
-
Selective Forms List — Enter the form number in the <formNumber> tag to request the global specification for the named online form.
Data structure details for the <request> tag appear in Exhibit 10-6
Exhibit 10-6. FORMS GBL LIST <request> Data Structure
| Subtag | Use | Occurs | Data Type & Length | Values & Dependencies |
|---|---|---|---|---|
| <formNumber> | Optional | 1 | String (3), variable | ZMF form ID of desired online form. NOTE: Asterisk (*) wildcard requests all forms. |
FORMS GBL LIST — Replies
The reply message for a global online forms list returns zero to many <result> data elements. Each <result> tag contains the global definition for one form identified by form number. Note that it includes two complex subtags with subordinate tags of their own: <notification> and <varList>.
The standard <response> data element follows the last <result> to indicate the success or failure of the request. Successful requests have a return code of 00. Unsuccessful requests have a return code of 04 or higher. As the last tag returned, the <response> tag also serves as an end-of-list marker.
Data structure details for the <result> tag appear in Exhibit 10-7
Exhibit 10-7. FORMS GBL LIST <result> Data Structure
| Subtag | Use | Occurs | Data Type & Length | Values & Dependencies |
|---|---|---|---|---|
| <allowAccess> | Optional | 0 - 1 | String (1) | Y = Yes, allow form users to edit form instances in package. N = No user edits allowed. |
| <formDesc> | Optional | 0 - 1 | String (255), variable | Global description of form. |
| <formNumber> | Optional | 1 | String (3), variable | ZMF form ID of returned online form. |
| <leadTime> | Optional | 0 - 1 | Integer (3), variable | Lead time required to act on the form request, in days. |
| <notification> | Optional | 1 - 10 | Complex | Approver notification list. Complex tag. See Exhibit 10-8. |
| <submitOnApproval> | Optional | 0 - 1 | String (1) | Y = Yes, automatically submit job stream on form approval. N = No, don’t automatically submit job stream on approval. |
| <varList> | Optional | 1 - 200 | Complex | User-defined variable list. Complex tag. See *Exhibit 10-9 |
<notification> Subtag
The <notification> data element lists users to notify and a notification method to use when a form is submitted for action. This is a complex, repeatable. Data structure details for the <notification> subtag appear in Exhibit 10-8.
Exhibit 10-8. <notification> Subtag
| Subtag | Use | Occurs | Data Type & Length | Values & Dependencies |
|---|---|---|---|---|
| <notifierTypeDesc> | Optional | 0 - 1 | Integer (8), variable | ZMF notification method used. Values: •MVSSEND •SERNET •BATCH |
| <userList> | Optional | 0 - 1 | String (44), variable | Delimited list of TSO user IDs or email addresses to notify by the method shown in <notifierType> when form is submitted for approval. |
Subtag
The <varList> data element defines the content of the form. Each instance of this complex tag defines an online form variable presented in the form’s ISPF panel. This is a complex subtag that is repeatable to accommodate multiple variables.
Data structure details for the <varList> subtag appear in Exhibit 10-9.
Exhibit 10-9. <varList> Subtag
| Subtag | Use | Occurs | Data Type & Length | Values & Dependencies |
|---|---|---|---|---|
| <varName> | Optional | 0 - 1 | String (8), variable | Name of user-defined form variable returned. Corresponds to data field in ISPF panel. |
| <varLen> | Optional | 0 - 1 | Integer (4), variable | Maximum length of variable data in bytes. Value range: 1 to 44. |
| <varFormat> | Optional | 0 - 1 | String (1) | Code for type of data in variable. Values: F = Fixed-length string. C = Variable-length character. |
| <isTableEntry> | Optional | 0 - 1 | String (1) | Y = Yes, data entry OK in field. N = No data entry permitted. |
| <isKeyField> | Optional | 0 - 1 | String (1) | Y = Yes, variable is table key field. N = No, not table key field. |
List Package Online Forms - FORMS PKG LIST
The package forms list function retrieves package forms associated with a package.
The Serena XML service/scope/message tags for a message to list package forms are:
<service name="FORMS">
<scope name="PKG">
<message name="LIST">
These tags appear in both requests and replies.
FORMS PKG LIST — Requests
The package forms list request may be customized using the form status tags.
Note
All yes/no status tags default to the value "Y" if no tag in the group has an explicitly assigned value. But if any flag tag in the group is explicitly assigned a value, all other tags in the group change their default values to "N."
Data structure details for the <request> tag appear in Exhibit 10-10.
Exhibit 10-10. FORMS PKG LIST <request> Data Structure
| Subtag | Use | Occurs | Data Type & Length | Values & Dependencies |
|---|---|---|---|---|
| <applName> | Optional | 0 - 1 | String (4), variable | ZMF application name. Same as first 4 bytes of package name. NOTE: OK to omit trailing blanks. NOTE: Not recommended as replacement for <package> tag. Use <package> instead of <applName> & <packageId>. |
| <filterActiveStatus> | Optional | 0 - 1 | String (1) | Y = Active status. N = Not active status. |
| <filterApprovedStatus> | Optional | 0 - 1 | String (1) | Y = Approved status. N = Not approved status. |
| <filterFrozenStatus> | Optional | 0 - 1 | String (1) | Y = Frozen status. N = Not frozen status. |
| <filterInactiveStatus> | Optional | 0 - 1 | String (1) | Y = Inactive status. N = Not inactive status. |
| <filterRejectedStatus> | Optional | 0 - 1 | String (1) | Y = Rejected status. N = Not rejected status. |
| <filterSubmittedStatus> | Optional | 0 - 1 | String (1) | Y = Submitted for approval status. N = Not submitted for approval status. |
| <filterUnfrozenStatus> | Optional | 0 - 1 | String (1) | Y = Unfrozen status. N = Not unfrozen status. |
| <formNumber> | Optional | 0 - 1 | String (3), variable | ZMF form ID of desired online form. |
| <package> | Required | 1 | String (10) | Fixed-format ZMF package name where desired instance of form resides. |
| <packageId> | Optional | 0 - 1 | Integer (6) | ZMF package ID number. Same as last 6 bytes of package name. NOTE: Leading zeroes required. NOTE: Not recommended. Use <package> instead of <applName> & <packageId>. |
FORMS PKG LIST — Replies
The reply message for a package online form list returns zero to many <result> data elements.
The standard <response> data element follows the last <result> to indicate the success or failure of the request. Successful requests have a return code of 00. Unsuccessful requests have a return code of 04 or higher. As the last tag returned, the <response> tag also serves as an end-of-list marker.
Data structure details for the <result> tag appear in Exhibit 10-11.
Exhibit 10-11. FORMS PKG LIST <result> Data Structure
| Subtag | Use | Occurs | Data Type & Length | Values & Dependencies |
|---|---|---|---|---|
| <applName> | Optional | 0 - 1 | String (4)), variable | ZMF application name. |
| <approver> | Optional | 0 - 1 | String (8)), variable | TSO user ID of approver. |
| <formDesc> | Optional | 0 - 1 | String (40), variable | Form description. |
| <formName> | Optional | 0 - 1 | String (8), variable | Form name. |
| <formNumber> | Optional | 0 - 1 | String (3), variable | Form number. |
| <formStatus> | Optional | 0 - 1 | String (1) | Form status: = Active = Approved = Frozen = Inactive 9 = Rejected = Submitted for approval = Unfrozen |
| <isAccessAllowed> | Required | 1 | String (1) | Y = Yes, access allowed. N = No, access not allowed. |
| <isApprovalSubmitted> | Required | 1 | String (1) | Y = Yes, approval was submitted. N = No, approval was not submitted. |
| <lastUser> | Optional | 0 - 1 | String (8) variable | TSO user ID of last user to update form. |
| <package> | Optional | 0 - 1 | String (10) | Fixed-format ZMF package name. |
| <packageId> | Optional | 0 - 1 | Integer (6) | ZMF package ID number. Same as last 6 bytes of package name. |
| <rejectReasons> <rejectReason01> . . . <rejectReason10> | Optional | 0 - 10 | String (72), variable | Reject reason text, zero to ten lines. |
| <user> | Optional | 0 - 1 | String (8) variable | TSO user ID of user who associated the form with the package. |
List Package Online Form Details - FORMS PKG DETAIL
The package form detail list function retrieves a package form definition previously created using online forms maintenance.
The Serena XML service/scope/message tags for a message to list a package form definition are:
<service name="FORMS">
<scope name="PKG">
<message name="DETAIL">
These tags appear in both requests and replies.
FORMS PKG DETAIL— Requests
The package form detail list request is identical to the FORMS PKG LIST request. Refer to Exhibit 10-10 for the <request> tag data structure details.
FORMS PKG DETAIL — Replies
The reply message for a package form detail list returns zero to many <result> data elements.
The standard <response> data element follows the last <result> to indicate the success or failure of the request. Successful requests have a return code of 00. Unsuccessful requests have a return code of 04 or higher. As the last tag returned, the <response> tag also serves as an end-of-list marker.
Data structure details for the <result> tag appear in Exhibit 10-12.
Exhibit 10-12. FORMS PKG DETAIL <result> Data Structure
| Subtag | Use | Occurs | Data Type & Length | Values & Dependencies |
|---|---|---|---|---|
| <is KeyField> | Optional | 0 - 1 | String (1) | Y = Yes, key field. N = No, not key field. |
| <is TableEntry> | Optional | 0 - 1 | String (1) | Y = Yes, table entry. N = No, not table entry. |
| <varDataLen> | Optional | 0 - 1 | Integer (4) | Length of variable data. |
| <varFormat> | Optional | 0 - 1 | String (1) | Variable format: C = Character F = Fixed |
| <varName> | Optional | 0 - 1 | String (8), variable | Variable name. |
| <variablePortionLen> | Optional | 1 - 10 | String (5), variable | Length of this portion |