Using the Editors

Chapter 24. JIF Editor

For JetNet and Oracle Tuxedo applications, the JIF is a file that contains information about services and service groups. For Oracle Tuxedo applications, the JIF can also contain information about reliable queues. The JIF is a central repository of all such information and is accessed by Panther to determine the requirements and specifications of services and queues. The JIF is stored in the distributed common library and is accessible to the team.

The JIF is a critical component of your JetNet and Oracle Tuxedo applications. It is accessed:

When a client makes a service call to determine the parameter types, number, and direction expected by a service, and to verify the validity of the service call.
When a server needs to determine what code should be executed to process a service call, that is, which JPL or C procedure maps to the service.
When the server needs information regarding a service's return data and parameters, and to identify the service component associated with the service.
When a server advertises its services.
When a service forwards data to another service, when a service receives data, and when data is returned to a client from a service.
(Oracle Tuxedo only) When a message queuing request is made, to identify the type of reliable queue and the expected data type of the message (if the queue is associated with a service), and the names and types of the data if the queue is independent, that is, not associated with a service.

If you use the screen wizard to create your client screens and service components, the wizard specifies service information on these screens. However, if you create your screens outside of the screen wizard, you need to specify the service information on the appropriate screens. In both instances you need to define the services in the JIF. The information provided in the JIF must match the information in the client screens and service components associated with a particular service.

You need to create a JIF or update it to define services, service groups, or queues. This chapter shows you how to create and edit a JIF using the graphical JIF editor.

The utility jif2asc is provided to allow you to convert a JIF between binary and ASCII formats.

Starting the JIF Editor

The JIF editor is an interactive tool used to create a new JIF or edit an existing one. You can invoke the JIF editor by choosing ToolsJIF Editor, or you can follow the directions for your environment:

How to Start the JIF Editor

In Windows:

Double-click on the JIF editor icon.
In Motif and Character Mode:

Type the following at the command line:
```
jifedit [jif-file]
```
Specify jif-file to start up the editor with an existing JIF loaded.
Note: If no jif-file is specified, Panther opens the JIF specified by the setup variable SMTPJIF. If you invoke the editor with no options, you can load a JIF file from the editor File menu.

The JIF Editor Workspace

At startup, the JIF editor workspace consists of three components: the View Services screen containing a list of services, a menu bar containing six pulldown menus (Panther) and seven pulldown menus (Oracle Tuxedo only), Help, and a toolbar.

Figure 24-1 The JIF editor workspace: the View Services screen, menu bar, and toolbar.

View Services Screen

The View Services screen displays the jifname@current_library name at the base of the screen. If you have invoked the editor naming an existing JIF, or if SMTPJIF is set to a JIF, the services appear in the list box.

Menu Bar

The JIF editor provides you with easy access to the operations and commands that help you define a JIF. This section provides a brief overview of each menu option and its contents.

File menu

File menu commands include:

New—Creates a new JIF, a new library, or a new remote library.
Open—Opens a JIF, a library, or a remote library. You can also connect to the middleware API if you are not already connected to it.
Close—Closes a library. You can also disconnect from the middleware API.
Remove—Deletes a JIF in a library.
Save—Saves the JIF with its current name. If the JIF is untitled, the Save As dialog box opens and you can save it with a name to a library. JIFs are by default saved in binary format. For more information on converting JIFs between ASCII and binary formats, refer to jif2asc in Application Development Guide.
Save As—Saves the JIF under a new name in a library.
Revert—Reverts to the last saved version of the JIF. An untitled JIF reverts to an empty JIF.
Source Mgmt—Provides access to your installed source code management tool (support for SCCS and PVCS). This option is only available if an open library is under source control management. Choose this option to check-in or check-out a JIF from a library. You can also choose to cancel the check-out request. The JIF is made read-only, and the lock on the JIF is released so other users can check out the JIF for editing purposes. For further information on source control management, refer to "Maintaining Libraries Under Source Control" in Application Development Guide.
Exit—Ends your session in the JIF editor. You are prompted to save the JIF that you created or changed but did not save.

Edit menu

Edit menu commands let you generate service code output, written to a Motif or Windows clipboard, or a file in character mode.

View menu

View menu options permit you to access lists of defined services, service groups, and queues in the JIF. You can toggle the options on and off to display or hide a particular screen. The jifname@current_library name is displayed at the base of each of the View screens. The View menu option screens provide a starting point for the update procedures of services, service groups, and queues.

Service menu

Service menu commands let you create, update or delete a service.

Group menu

Group menu commands allow you to create, update or delete a service group.

Queue menu

(Oracle Tuxedo only) Queue menu commands let you create, update or delete a queue.

Windows menu

Windows menu commands provide access to all open windows in your screen editor workspace. Select an item from the list to bring focus to that window.

Help menu

Help option provides general overview help or help on the currently active window.

Defining and Updating Services

You can specify service information on the client screens and service components via the screen wizard or independent of the wizard. In both instances, you use the Create Service screen to define new services. On the Create Service screen, you enter and select data that describe a service. The service description and the service options in the JIF must match the information in the client screens and service components associated with the described service. These services can later be included in service groups. For further information on service groups, refer to "Defining and Updating Service Groups."

How to Define or Update a Service

Depending on the desired task, do either of the following:
- To define a new service, choose ServiceCreate (or the Create Service button on the toolbar). The Create Service screen opens.
- To update an existing service, choose ViewServices. The View Services screen opens. Select the service that you want to edit and choose ServiceUpdate, or double-click on the desired service. The Update Service screen opens.
  
  Note: The Update Service screen contains information for the specified service. It is identical to the Create Service screen except for its title bar.
  
  Figure 24-2 Define a service with the Create Service screen.

Enter or modify the name of the service in the Service Name field. Each service name must be unique in the JIF and can be no greater than 15 characters.

If you used the screen wizard to generate your screens, the service name includes a suffix that indicates the particular transaction manager operation that a service implements. In this case, when you tab into the Routine Name field or the Service Component field, the JIF editor automatically enters the appropriate information into both these fields.

**Table 24-1 JIF defaults for screens generated by the screen wizard**
Operation type	Service Name	Routine name	Service component
Select	`servicePrefix``_s`	`select`	`servicePrefix`
Insert	`servicePrefix``_i`	`insert`	`servicePrefix`
Update	`servicePrefix``_u`	`update`	`servicePrefix`
Delete	`servicePrefix``_d`	`delete`	`servicePrefix`
Link_`addtnlTable`	`servicePrefix``_l1`	`val_link`	`servicePrefix`
Choose_`addtnlTable`	`servicePrefix``_c1`	`choose`	`servicePrefix`

If you created your screens without the screen wizard, the service name should not include the suffix that indicates the transaction manager service. In this case, when you tab into the Routine Name field or the Service Component field, the JIF editor automatically duplicates the name of the service in both the fields. To enter a different name, edit the text in the appropriate field.

Tab to the Routine Name field. Enter or modify the name of the JPL module or C routine which contains the service code that implements the service. Each routine name can be no greater than 31 characters.
Note: If you used the screen wizard to generate your screens, you will find the appropriate routine name in this field.
Tab to the Service Component field. Enter or modify the name of the service component associated with the service.
Note: If you used the screen wizard to generate your screens, you will find the appropriate service component name in this field.
Define the transport methods. Select or change the buffer type that is used to transport data to and from the service. The direction of the flow of information between the client and the server for the service is as follows:
Choose Add.
The View Services screen is automatically updated as services are defined or modified during an editing session.

Controlling Service Behavior

The service options allow you to control which transaction a service implements, when a service component is opened and cached to memory, and the behavior of the service itself when it is called.

To specify service options, choose the Options button on the Create Services screen or the Update Services screen, as the case may be. The Update Service Options screen opens.

Figure 24-3 Control service behavior with the Update Service Options screen.

You can control the behavior of services by specifying service options on the Update Service Options screen. The options are as follows:

Defining and Updating Service Groups

A service group is a collection of services; services can be grouped in several different ways. Services are grouped to facilitate advertising services in servers. Services contained within a unique server can be defined as a service group. In addition, services can also be grouped into multiple service groups within one server. If you have multiple service groups in a server, it should be a logical grouping based on the application's tasks. For example, in a banking application, you might want to group all the services that can be accessed from an ATM client.

You use the Create Group screen to create groups and to include services in these groups. You can create service groups without any services in them; however, you can add existing services to these service groups. For further information, refer to "Defining and Updating Services."

How to Define or Update a Service Group with Services

Depending on the desired task, do either of the following:
- To define a new service group, choose GroupCreate (or the Create Group button on the toolbar). The Create Group screen opens.
- To update a service group, choose ViewGroups. The View Groups screen opens. Select the service group that you want to edit and choose GroupUpdate, or double-click on the desired service group. The Update Group screen opens.
  
  Note: The Update Group screen displays the services currently in the group. It is identical to the Create Group screen except for its title bar.
  
  Figure 24-4 Define a service group with the Create Group screen.
Enter or modify the name of the group in the Group Name field. The group name must be unique in the JIF and can be no greater than 31 characters.
To add services to the group or remove unwanted services from the group, do the following as needed:
- Select services in the Available Services list and choose the Assign button to transfer selected services to the Assigned Services list, or double-click on a service in the Available Services list to transfer it to the Assigned Services list.
- Select the unwanted services in the Assigned Services list and choose the Remove button, or double-click on an unwanted service in the Assigned Services list.
  
  Note: You can click+drag or Shift+click to select contiguous services or use Ctrl+click to select non-contiguous services in the list boxes.
  The Assign All and Remove All buttons provide shortcuts to include all services in the group or remove all services from the group.
Choose Add.
The View Groups screen is automatically updated as service groups are defined or modified during an editing session.

How to Delete a Service Group

Choose ViewGroups. The View Groups screen opens.
Select the service group and choose GroupDelete.
The View Groups screen is automatically updated as services are deleted during an editing session.

Defining and Updating Queues

The Oracle Tuxedo middleware adapter uses a System/Q feature that allows messages to be queued—stored in stable memory and processed later. A queuespace contains queues, and queues contain messages. Messages are enqueued (pushed onto a queue), dequeued (released from a queue), and forwarded to either clients or servers, as the case may be. For further information about the System/Q feature, refer to "Reliable Queues" on page 8-11in JetNet/Oracle Tuxedo Guide and refer to the Oracle Tuxedo/Q Guide in the Oracle Tuxedo documentation.

To process messages, you need to identify your queues and their respective queuespaces in the JIF. Queues are uniquely identified by their name and the name of the queuespace to which they belong. A queue can be either associated with a service or be independent. The parameters for a service queue are defined via its associated service, while the parameters for an independent queue are self-defined. In a service queue, enqueued messages get forwarded to the associated service having the same name as the queue. In an independent queue, messages are enqueued and dequeued explicitly by an agent.

How to Define or Update an Independent Queue

Depending on the desired task, do either of the following:
- To define an independent queue, choose QueueCreate. The Create Queue screen opens.
  
  The default queue type is specified to be an independent queue.
- To update an independent queue, choose ViewQueues. The View Queues screen opens. Select the queue to be updated and choose QueueUpdate, o² double-click on the selected entry. The Update Queue screen opens.
  
  Note: The Update Queue screen displays the independent queue's current definition. It is identical to the Create Queue screen for an independent queue except for its title bar.
  
  Figure 24-5 Define an independent queue with the Create Queue screen.
Enter or select the queuespace name in the Queuespace combo box. Each queuespace name can be no greater than 15 characters.
Note: You cannot modify the queuespace name if you are updating a queue.
Enter or modify the name of the queue in the Queue field.
Note: Queues are uniquely defined by their name and the queuespace to which they belong. Queue names need only be unique within a given queuespace.
For Transport Methods, select or change the argument type from the option menu and, for string arguments, enter the name in the field that appears.
Optionally enter or select a reply queue in the Reply combo box and/or a failure queue in the Failure combo box.
- Reply queue—The queue might define a reply queue onto which replies will be enqueued. If there is one defined, its queuespace is also provided.
- Failure queue—The queue might define a failure queue onto which failure notification messages will be enqueued. If there is one defined, its queuespace is also provided.
  
  Note: If the reply queue or failure queue does not exist in the current queuespace, then it is created in this queuespace when the user chooses OK.
Choose Add.
The View Queues screen is automatically updated as independent queues are defined or updated during an editing session.

How to Define or Update a Queue Associated with a Service

Depending on the desired task, do either of the following:
- To define a service queue, choose QueueCreate. The Create Queue screen opens. Choose the Service radio button. The screen updates to show the new service queue.
- To update a service queue, choose ViewQueues. The View Queues screen opens. Select the queue to be updated and choose the Modify button, or double-click on the selected entry. The Update Queue screen opens.
  
  Note: The Update Queue screen displays the service queue's current definition. It is identical to the Create Queue screen for a service queue except for its title bar.
  
  Figure 24-6 Define a service queue with the Create Queue screen.
Enter or select the queuespace name in the Queuespace combo box. Each queuespace name can be no greater than 15 characters.
Note: You cannot modify the queuespace name if you are updating a queue.
Enter or modify the name of the queue in the Queue field. Each queue name can be no greater than 15 characters.
For INPUT queues, the name of the queue must be the same as the name of the service associated with it. Thus, the associated service must already be defined and you must know its name before you enter the name of the queue.
Note: Queues are uniquely defined by their name and the queuespace to which they belong. Queue names need only be unique within a given queuespace.
Choose or change the queue type by selecting one of the following options:
Record or select the associated service in the Services option box depending on the chosen queue type. It is as follows:
Choose OK.
The View Queues screen is automatically updated as service queues are defined or updated during an editing session. This screen lists the queues belonging to the selected queuespace.

How to Transfer a Queue to Another Queuespace

You can only change a queue's membership if there are two or more queuespaces.

Choose ViewQueues. The View Queues screen opens.
Select the queue you wish to move from one queuespace to another and choose the Transfer button on that screen. The Queue Transfer screen appears.

Figure 24-7 The Queue Transfer screen is used to move a queue to a different queuespace.
Select two queuespaces from their respective option boxes.
Select the queues that you wish to move from the list under the appropriate queuespace.
Note: You can click+drag or Shift+click to select contiguous queues or use Ctrl+click to select non-contiguous queues in the list boxes.
Choose the single arrow button that points in the direction toward the queue list to receive the queues.
If you want to move all queues from one queuespace to another, choose the double-arrow button that points in the direction of the queue list to receive the queues.
Choose OK.
The View Queues screen is automatically updated as queues are transferred between queuespaces. This screen lists the queues belonging to the selected queuespace.

How to Delete a Queue

Choose ViewQueues. The View Queues screen opens.
Select the queue and choose QueueDelete.
The View Queues screen is automatically updated as queues are deleted during an editing session.

JPL Code Generation

When you create your screens in the screen wizard, the JPL code for services and service requests is automatically generated and accessible to the screens. However, if you create your client screens and service components from scratch, then you need to generate your own service definition code and service request code. The JIF editor provides an easy-to-use mechanism for generating JPL code for services and service requests. The generated JPL code can be implemented as a:

Widget or screen module.
Library module.
Text file outside of Panther.

Service Code Generation

The JIF contains the necessary information about services that you defined via the Create or Update Services screen and can output this information to a template that generates the appropriate JPL code. You can generate the following two types of service code:

Service definition code.
Service request code.

In Windows and Motif, the service code is generated to the clipboard. In character mode, the code is written to a file. The output for code generated to either the clipboard or a file is as follows:

Output For Service Definition Code

proc routine-name
	receive args (service-parameters)

	service_return (return-data)

routine-name is the name of the JPL or C procedure which will perform the named service, identified in the Routine Name field of the Create or Update Service screen.

service-parameters are the representations for the IN parameters.

return-data are the representations for the OUT parameters.

Output For Service Request Code

service_call service-name (argument-list)

service-name is the name of the service, as identified in the Service Name field of the Create or Update Service screen.

argument-list are the representations of the IN and OUT parameters.

Generating Service Code

You can generate service code to the clipboard or file, as the case may be. However, for character mode, you have to set the configuration variable SMTPCLIPFILE either in the environment or in SMVARS. You need to set the value of this variable to the full path name of the file where you want the code written. If SMTPCLIPFILE is not set, the default file name is clip.dat.

How to Generate Service Code

To generate service code, you need to make the service information available. Depending on whether you have defined your service or not, do either of the following:
- If you have an already defined service, select the service in the View Services screen.
- If you have not defined your service, choose ServiceCreate and enter the service data; then select the service in the View Services screen.
Do either of the following to generate the desired code:
- Generate service definition code. Choose EditCopy Service (or the Copy Service button on the toolbar). The output JPL code is written to the clipboard for GUIs and to the SMTPCLIPFILE file for character mode.
- Generate service request code. Choose EditCopy Request (or the Copy Request button on the toolbar). The service call code is written to the clipboard for GUIs and to the SMTPCLIPFILE file for character mode.
Paste the code, from the clipboard, to a file within a text editor. You can also paste code from the clipboard to the JPL Program Text window.
In character mode, remember to copy the contents of the file before the facility is used again, since SMTPCLIPFILE is overwritten each time code generation is done.

Format of Template

The format of the template used to generate code can be found in the config/msgfile. The values that undergo variable substitutions are enclosed in double angle brackets ("<<...>>"). These directives are replaced by the values that have been designated in the service's definition in the JIF. You can edit the template code in the msgfile, but you cannot create new directives. The template message strings that you can edit are as follows:

TP_JED_CLIP_TMPL_REQUEST

TP_JED_CLIP_TMPL_SVC

**Table 24-2 Recognized directives in the template**
Directive	Replaced with
`<<service_name>>`	Name of the service, as given in the Service Name field.
`<<routine_name>>`	The JPL or C routine that contains the code for the service, as given in the Routine Name field.
`<<service_component>>`	The name of the service component associated with the service, as given in the Service Component field.
`<<arg_list>>`	A list of 0, 1 or 2 arguments.
`<<args_in>>`	The arguments that are sent to the service.
`<<args_out>>`	The arguments that are returned by the service.