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:

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


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:

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

  1. Depending on the desired task, do either of the following:
  2. 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.

  3. 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.

  4. 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.

  5. 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:
  6. 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:

Transaction Type

The transaction options determine the type of transaction manager operation that a service implements. To specify the transaction type, choose the Use Transaction Manager check box. The transaction type options are activated.

The default is set to Select. The options are as follows:

Cache Service Component

The options control the relationship between a service and when its service component gets opened, closed, and cached to memory. The default is set to On Advertise. The options are as follows:

On Advertise
Opens a service component when a service is advertised and caches the service component to memory. When the service is called, the service component gets selected; the service component gets deselected after the service returns.

On First Call
Opens the service component when a service is first called and caches the service component to memory. If the service component is already cached in memory, this option selects the service component when the service is called.

No Cache
Opens the service component for the duration of the service and closes it when the service completes. The container is not cached.

Reply Options

The reply options determine whether or not the sender of the request waits for a reply. The default is set to Sync. The options are as follows:

Sync
A synchronous service call is when the sender of the request waits for the reply (when the service call command returns after the service being called completes).

Async
An asynchronous service call is when the sender of the request does not wait for the reply (when the service call command returns before the service being called completes).

Async, No Reply
An asynchronous service call with no reply is when the sender of the request does not expect a reply (when the service call command returns before the service being called completes and there is no reply for the service).

Call Options

The call options determine the order in which services are processed, the time taken for services to be processed, where the service call is executed, which handler should be used, and what priority a service should hold. You can set or unset the following call options:

Timeout
Select to specify that a service call on encountering a blocking situation should be subject to the default blocking timeout of 60 seconds (default). Deselect to specify that a service call on entering a blocking situation can wait indefinitely and is not subject to the blocking timeout. A blocking timeout specifies how much time elapses before a service call times out and returns to its caller. However, in Oracle Tuxedo applications, transaction timeouts remain in effect. For further information on setting the default blocking timeout, refer to Default Blocking Timeout in JetNet/Oracle Tuxedo Guide.

Outside Transaction
In Oracle Tuxedo applications, select to specify that the service call should be executed independently of the active transaction, if one exists. Deselect to specify that the service call be executed within the active transaction (default).

Exception Handler
Specify the name of an exception handler (either a Panther variable or a string) to handle any exceptions that might occur as a result of either sending the request or receiving the response. If you do not specify an exception handler, the default is the application-wide exception handler.

In Oracle Tuxedo applications, if you do not specify an exception handler, the default is the transaction handler. However, if a transaction handler is not specified when a transaction is active, then the default is the application-wide handler. For more information on exception events and handlers, refer to "Exception Events" in JetNet/Oracle Tuxedo Guide.

Unload Handler
Specify the name of an unload handler (either a Panther variable or a string) to handle any unload events that might occur as a result of receiving the response from the service. If you do not specify an unload handler, the default is the application-wide unload handler.

In Oracle Tuxedo applications, if you do not specify an unload handler, the default is the transaction handler. However, if a transaction handler is not specified when a transaction is active, then the default is the application-wide handler. For more information, refer to "Unload Handlers" in JetNet/Oracle Tuxedo Guide.

Priority
Establishes a priority that determines the order in which service calls get carried out. The value can be an absolute (unsigned) integer between 1 and 100, inclusive (default is 50). The higher the value, the greater the priority of the service call.

How to Delete a Service

  1. Choose ViewServices. The View Services screen opens.
  2. Select the service and choose ServiceDelete.

    The View Services screen is automatically updated as services are deleted during an editing session.


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

  1. Depending on the desired task, do either of the following:
  2. 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.
  3. To add services to the group or remove unwanted services from the group, do the following as needed:
  4. 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

  1. Choose ViewGroups. The View Groups screen opens.
  2. 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

  1. Depending on the desired task, do either of the following:
  2. 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.

  3. 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.

  4. 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.
  5. Optionally enter or select a reply queue in the Reply combo box and/or a failure queue in the Failure combo box.
  6. 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

  1. Depending on the desired task, do either of the following:
  2. 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.

  3. 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.

  4. Choose or change the queue type by selecting one of the following options:
  5. Record or select the associated service in the Services option box depending on the chosen queue type. It is as follows:
  6. 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.

  1. Choose ViewQueues. The View Queues screen opens.
  2. 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.

  3. Select two queuespaces from their respective option boxes.
  4. 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.

  5. 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.

  6. 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

  1. Choose ViewQueues. The View Queues screen opens.
  2. 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:

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:

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
  1. 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:
  2. Do either of the following to generate the desired code:
  3. 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:

The text that replaces the argument directives listed in Table 24-2 depends upon the transport mechanism that they correspond to:

The JetNet-specific buffer types are JAMFLEX and none. The Oracle Tuxedo-specific buffer types are JAMFLEX, FML, FML32, STRING and none.

Two arguments in <<arg_list>> are separated by a comma.

If directives are unintentionally created that are unrecognized, they are stripped of their angle brackets. Also, directives can be \Qescaped' (for example, to be used in a comment) by enclosing them in another set of angle brackets. The following are examples of how text with embedded angle brackets in the template code is interpreted by the JIF editor.

Text Replaced with

<<unrecognized>>

unrecognized

<<<service_name>>>

<service_name>

<<<<service_name>>>>

<<service_name>>