In this post I mentioned that the recent OB700 IF1 update had added additional security checking for KOBASE and 04SRV resources and that without suitable RACF (or other security product) profiles to give the user read access to these resources, users would not be able to log on to the Enhanced 3270 UI.
PTF UA71750 is now available and removes the security checking on these resources. As a result, these additional security profiles are no longer required.
If you need to know more about the PARMGEN configuration tool for the ITM z/OS environment, here are a couple of videos about it.
What is PARMGEN
Convert an ICAT RTE to PRMGEN and Upgrade the Products
Global settings selection
May aspects of the operation of OMEGAMON XE for CICS on z/OS data collection and operation are controlled by global settings. These settings are held in a PDS member of the library allocated to the RKC2GLBL DD in the ‘classic’ collector address space (also known as the OCCI). Typically the hlq.RKANPARU library is allocated to the RKC2GLBL DD
Global members have member names of the form KC2GLBxx where xx is a two character suffix. The global member to be used by the OCCI when monitoring a given CICS region is selected by including a KOCGLBxx dummy DD in the CICS startup JCL, where the xx in the DD name matches the suffix of a global member in the library allocated to the RK2GLBL DD in the OCCI address space.
If you do not add a KOCGLBxx DD to the CICS region, then xx defaults to ’00’ (zero zero). If the selected global member is not found by the OCCI address space then it uses a default set of values.
PARMGEN support for the CICS globals
Currently PARMGEN support for the CICS globals is limited to copying global members from a source PDS into the run time environment’s hlq.RKANPARU library.
The source PDS to be used is specified by the KC2_CLASSIC_KC2GLB_SRCLIB parameter in the rte member name in the PARMGEN WCONFIG library and defaults to the ICAT INSTDATA dataset.
If you are not converting from an ICAT install for the RTE you can point this parameter at any library you chose and place your completed global members in there. During the deployment phase of the RTE, the deployment jobs will copy the global members from this library to the run time’s hlq.RKANPARU library.
If you are NOT using the default global member for a CICS region you will still need to manually add a KOCGLBxx dummy DD card to the CICS startup JCL in order to select the corresponding global member.
The deployment phase (step 11 on the menu) of creating and loading an RTE with PARMGEN copies all the run time data to the run time libraries. Some of these members need to go into system libraries such as SYS1.PROCLIB and SYS1.VTAMLST or your user versions of same.
Rather than overwrite my current live run time procedures and VTAMLST members I configure PARMGEN to write them to ‘staging’ libraries. From there I can double check them against the current live members before committing them.
To configure PARMGEN to write to your own system data sets, edit the $GBL$USR member in WCONFIG by selecting option 8 on the main menu and then option 2 and change the highlighted lines shown in this screen shot:
You have to manually create these data sets yourself but that is easy enough using ISPF option 3,2.
After the initial deployment, most of the time you will only need to copy run time JCL from the proclib and possibly vtam list members from the vtamlst staging libraries to your actual live system data sets.
If you are using the TCP/IP protocol (defined in ITM as IP.PIPE, IP6.PIPE or IP6.SPIPE) as a transport protocol between your ITM components on z/OS then you may need to consider configuring TCP/IP to reserve specific ports for use by the ITM components in order to prevent other non ITM address spaces from acquiring them.
ITM TCP/IP port allocation algorithm
ITM and ITM agents use the following rules to allocate TCP/IP ports
- The Hub or Remote TEMS always uses the well known port, typically 1918.
- The agents then attempt to acquire ports in sequence using the algorithm well known port + (n*4096) until they either obtain a port or they run out of ports to try. The actual starting port and number of attempts can be controlled by the SKIP and COUNT parameters as described later.
For example, if the well known port assigned to the hub or remote TEMS is 1918, the first agent to start will attempt to obtain port 1918+(1*4096) or 6014. If that fails, it will attempt to obtain port 1918+(2*4096) or 10110 and so on.
The actual port assigned to any given agent for any given execution will vary based on the startup order of the agents and various other timing related factors but will always follow the above pattern.
Thus you can predict the port numbers that will be required by the ITM infrastructure on a given LPAR.
Using 1918 as a starting point, the following port numbers are potential candidates for use by ITM:
1918 – Always assigned to the hub or remote TEMS
Notice that this means you can have a maximum of one hub or remote TEMS and 15 agents on an LPAR.
What are the potential problems?
Unless you take specific action by configuring TCP/IP, there is nothing to prevent any other non ITM application on a z/OS LPAR from using any of these ports. Thus it is entirely possible that enough of these ports are in use by other applications that there are not enough for all the ITM agents, resulting in connectivity issues.
This type of problem can be difficult to diagnose since it may only occur randomly as it depends on the the unavailability of specific ports, and that will depend on which other application are running and the ports they have acquired.
What ports do I need to reserve?
If you are running for example, a remote TEMS and four agents on a z/OS LPAR then the environment will need as a minimum, the well known port plus four additional ports. The four additional ports do NOT have to be consecutive (using the list above). In the absence of the SKIP and COUNT parameters, each agent will try specific ports from the list (assuming 1918 as the base well known port) until it obtains a port. So you could quite validly reserve for example, ports 34686, 38782, 42878, 46974 for use by the four agent address spaces. In that case you might want to use the SKIP parameter to prevent agents from attempting to bind to the the first 7 ports in the list.
Remember, these examples are based on 1918 being the well known port. The actual values in use will change if you use a different port number for the well known port.
Reserving port in TCP/IP
The PROFILE DD of the TCP/IP started task JCL points to a dataset, or more typically a member of a dataset, that configures the TCP/IP environment. Within this configuration dataset or member you can use entries within the PORT statement to restrict specific ports to specific address spaces.
The port section might look like this:
7 TCP MISCSERV
7 UDP MISCSERV
9 TCP MISCSERV
9 UDP MISCSERV
19 TCP MISCSERV
19 UDP MISCSERV
20 TCP OMVS
Where the first value of each line is the port number, the second value is the protocol and the third value is the name of the address space that the port is limited to.
The critical port to reserve for ITM is the well known port which is typically 1918. So if your TEMS address space is named CANSDSST and the well known port is 1918 then you could add the following entry to the TCP/IP configuration deck PORTS section
1918 TCP CANSSDDT
This would prevent any other address space from obtaining port 1918.
Do I need to reserve ports for the agents?
The way that the allocation algorithm works allows you to have up to 15 agents running on an LPAR. If you only have a few agents on an LPAR then even if there are some ports from the potential list in use by non ITM applications, there are probably enough free ports from the list of potential ports to satisfy the needs of the agents.
However, if you have a lot of agents on an LPAR or if you want to guarantee that specific ports are available to the ITM agent address spaces then you may need to reserve specific ports to specific agents address spaces in order to ensure that they are available for the agent address spaces.
There are a couple of ways to do this:
- Configure TCP/IP to allow any agent to connect to any of the potential ports
- Configure each ITM agent to use a specific port and limit each port to a specific address space in the TCP/IP profile.
Configure TCP/IP to allow any agent to connect to any of the potential ports
The advantage of this method it that it only requires TCP/IP configuration and allows ITM to continue to dynamically assign ports to each agent based on availability and startup sequence. For example, if you had three agent started tasks CANSCICS, CANSMQ and CANSMFN, you would need to configure TCPIP to reserve all the potential ports for each address space as follows:
6014 TCP CANSCICS
6014 TCP CANSMQ
6014 TCP CANSMFN
10110 TCP CANSCICS
10110 TCP CANSMQ
10110 TCP CANSMFN
14206 TCP CANSCICS
14206 TCP CANSMQ
14206 TCP CANSMFN
etc all the way up to port 63358
Obviously as you add more agent address spaces you have to add more entries for each port.
Configure each ITM agent to use a specific port and limit each port to a specific address space in the TCP/IP profile.
This method uses a combination of ITM and TCP/IP configuration options to achieve the desired result. The advantage of this method is that the port assigned to each agent address space is predictable.
First, lets configure TCP/IP to reserve a single specific port for each agent address space:
6014 TCP CANSCICS
10110 TCP CANSMQ
14206 TCP CANSMFN
Now you need to configure each agent to only use a specific port. To do this you need to edit the KDE_TRANSPORT IP.PIPE (and/or IP6.PIPE or IP6.SPIPE if in use) entry of each agent’s KppENV member in RKANPARU as follows:
For the CICS agent address space CANSCICS:
KDE_TRANSPORT=IP.PIPE PORT:1918 USE:Y COUNT:1
For the MQ agent address space CANSMQ:
KDE_TRANSPORT=IP.PIPE PORT:1918 USE:Y COUNT:1 SKIP:1
For the MFN gent address space CANSMFN:
KDE_TRANSPORT=IP.PIPE PORT:1918 USE:Y COUNT:1 SKIP:2
The COUNT:1 parameter tells the agent address space to only try 1 port number from the potential list or ports.
The SKIP parameter tells the agent address space to skip that number of ports in the available list before trying to bind to the port. It is not required for the CICS agent (in this example) because the CICS agent address space will bind to the first port in the list.
Remember, these examples are based on the well know port number being 1918.
High Availability Hubs
A high availability hub is a hub TEMS address space that uses a DVIPA IP address to enable it to run on any candidate LPAR (one with the DVIPA address configured) within the sysplex. The location of the IP address moves with the hub address space so that as it moves from LPAR to LPAR, the agents and remote TEMS can connect to it, no matter where it is.
A hub TEMS uses the same well known port number as the rest of the ITM infrastructure (remote TEMS), however because a high availability hub connects to a different IP address (the DVIPA address) from that defined for the host LPAR, the high availability hub can execute on the same LPAR as a remote TEMS, even though both are using the same well known port.
However, if you have reserved the well known port on each LPAR for a remote TEMS address space, you must also reserve the same address for the high availability hub address space name.
So, in the PORT section of the TCPIP profile dataset or member you might have the following entry to reserve the well known port 1918 for the remote TEMS:
1918 TCP CANSSDDT
To this you would need to add (assuming the high availability hub address space name is CANSHAHB):
1918 TCP CANSHAHB
Both address spaces can bind to the same port because the high availability hub is using the DVIPA IP address.
Refreshing the TCPIP configuration
After making changes to the TCPIP profile dataset or member you can use the OBEYFILE command to cause the TCPIP address space on an LPAR to reload its configuration file.
Listing reserved ports
You can list the currently configured TCP/IP reserved ports using the TSO NETSTART PORTLIST command.
In TSO, issue the command:
NETSTAT PORTLIST [REP DSN dsn]
The REP DSN dsn option causes the command to write the output the to the dataset specified by the dsn operand.
Remember. Just because a port or address space name is defined in the TCPIP profile dataset or member does not mean it is actually defined to TCP/IP. You must restart TCPIP or issue the OBEYFILE command to refresh the TCPIP configuration.
Diagnosing Port Permissions Problems
In the agent or RTEMS RKLVLOG output you may see this sort of message:
(0017-D69321E3:kdebbbi.c,128,”KDEB_BaseBind”) Status 1DE00000=KDE1_STC_CANTBIND=2: EACCES
(0018-D69321E3:kdebbbi.c,132,”KDEB_BaseBind”) <0x29615378,0x10> bind: ASD 289FD7A0, status 1DE00000, errno 2
+0018 00000000 00022774 092A2E16 00000000 00000000 …………….
- KDE1_STC_CANTBIND indicates a bind failure.
- EACCES indicates the bind failed because of a permissions issue. The address space is not authorized to bind to the port.
- The port number (in hex) is the lower four digits of the word indicated in the message above. In this case 2774 (hex) is port 10100 decimal.
Use the NETSTAT PORTLIST command to determine if the address space is authorized to access the port, for example:
NETSTAT PORTLIST (PORT 10100
The (PORT portnumber operand limits the output to just the requested port.
A note about EACCES issues.
My research indicates that an EACCES return code is returned when the application first attempts to use a port, NOT when it is allocated. What this means for ITM is that the port allocation algorithm may select a free port that is actually restricted by TCP/IP. However ITM will not find out about this until it tries to bind to the port. At that point the port allocation process is complete so you end up with an assigned port that you cannot use.
In this instance I believe the only solution is to use the COUNT and SKIP parameters to force agents to only use ports in specific ranges and to avoid any reserved port ranges. You don’t have to assign a specific port to each agent, you can still let them pick from a range based on first available but if you have for example, a range of reserved ports in the middle of the normally free range of ports, you may need to configure some agents to only use ports below that reserved range and others to use the ports above the range.
The actual configuration you need to use to make the agents avoid the reserved range or ranges will depend on the number of agents you are running on the system and where in the list of normally free ports, the reserved range or ranges are.
This article will describe how to customize or create your own IBM OMEGAMON XE Enhanced 3270 User Interface (E3270UI) workspaces.
Before modifying an product supplied workspace member it is recommended that you copy it from the hlq.TKANWENU or hlq.RKANWENU library to the hlq.UKANWENU library and make the modifications there. Remember that any changes you make will be seen by all users of the E3270UI therefore you might want to clone the E3270UI started task JCL and create you own instance of it with your own private WENU workspace library concatenated in front of the standard ones, so that you can develop and test your changes without impacting anyone else.
You could also allocate your own workspace library in front of the standard ones but allocate the concatenation to you own RKANWxxx library where xxx are the last three characters of the LOCALEID specification in your own profile member. See part 1 of this series for more details.
Standard Workspace Structure
The Workspace Header Section
In addition to the standard workspaces that you see on the E3270UI screen there are also popup and silent workspaces. In this article we shall just be looking at a standard workspace.
Within a workspace, comments on a line are indicated by a /* (slash asterisk) string. There is no need for a closing */ (asterisk slash). Comments are NOT continued across lines so each must be preceded by a /*.
A workspace definition consists of a header section that starts with a <WORKSPACE> stanza followed by one or more sub panel definitions and ending with a </WORKSPACEEND> stanza.
The <WORKSPACE> stanza must be the first non-comment line in the workspace source member.
A typical workspace header might look like this:
HEADER=’CICS Region Overview’
The HEADER text ‘CICS Region Overview’ appears on the fourth line of the screen.
The two navigation fields in the top right corner are referred to as NAV1 and NAV2. You set the text to be displayed in the caption (in blue on the above screen shot) using the NAV1TEXT and NAV2TEXT keywords.
If you set the appropriate ZOMEGLOCK1 or ZOMEGLOCK2 to NO then the user can overtype the corresponding input field to change the context of the data being displayed on the workspace, such as overtyping the ‘Region’ name in the above screen shot of an OMEGAMON XE for CICS on z/OS workspace to change to a different CICS region within the same CICSplex. The actual implementation and use of these two fields is product specific. Setting ZOMEGLOCK1 or ZOMEGLOCK2 to YES will prevent the user from overtyping the corresponding field.
A sub panel definition within a workspace starts with a <SUBPANEL> stanza. There is NO corresponding closing stanza, the next <SUBPANEL> or </WORSPACEEND> stanza defines the end of the sub panel definition.
There are two different type of sub panel, DETAIL and SUMMARY. A DETAIL sub panel is used to show data about a single row of data as a block on the screen:
If you know that there will only ever be ONE row of data returned, you can use either style of sub panel. Be aware though that there are differences in the way navigation to other workspaces works between the two styles of sub panel, as described in my earlier E3270 Overview article.
A Typical Sub Panel header might like this:
The TYPE=DETAIL line defines this as a detail sub panel.
The HEADER line creates a sub panel header. Notice that it contains a variable, &CICSNAME. This variable would have been set by an earlier workspace by the navigation process. We will look at setting variables later.
The LINES statement defines the number of lines that the sub panel should occupy. For a detail sub panel you must ensure that you have enough lines and columns to display all the attributes specified by the DISPALYCOLS keyword. For example, if you specify LINES=5 and COLUMNS=2 but then specify eleven attribute names in the DISPLAYCOLS statement, you will not see the eleventh attribute!
This defines the number of columns of data to be shown. For example, this is a two-column detail display:
The default is DYNAMIC, which allows the E3270UI to control the formatting of the sub panel.
There are also COLUMNS132 and COLUMNS160 keywords that can be used to specify the number of columns to be displayed on 3270 screens with a 130 or 160 character wide display.
Following the sub panel header section are the following lines:
These relate to the way the sub panel query is run. DO NOT MESS WITH THESE!
If the QUERYWHEN option is NOT specified then after having navigated forward from this workspace, as you navigate back to it using F3 the previous data is displayed. The query associated with the sub panel is NOT run again.
If you specify QUERYWHEN=RETURN then as you navigate backwards to the workspace, the query is run so that the sub panel shows the latest data, not the old data.
The WHENNODATA keyword defines the behavior when there is no data to display in this sub panel. There are a number of options as follows:
- Collapse. Only the sub panel header, collapse/expand twisty, and the minimize and close buttons are displayed. This is the default.
- Minimize. The sub panel is minimized down to the task bar
- End. If no data is retrieved on the initial query or entry to the workspace, the sub panel is “deleted” from the workspace. This option is useful for queries that will either return data or will not, but that condition will not change if the workspace data is refreshed by pressing ENTER.
- Shrink. The number of rows in the sub panel is dynamically decreased to zero when there is no data.
- Hide. Use instead of End if you want the sub panel to reappear when data is available again.
The QUERY statement defines a standard ITM SQL Query that will be sent to the ITM framework via a Data Retrieval Agent (DRA).
The DISPLAYCOLS statement names the attributes that are to be displayed on the sub panel. The attributes are displayed in the order specified. Any attribute name you specify here must also be specified in the QUERY statement, however you do not have to display every attribute that the query retrieves.
You might retrieve certain attributes in the query in order to set variables from their values for later use as you navigate forward from this workspace. ORIGINNODE (the managed system name) is a typical example.
By default, each attribute is displayed using the same attribute caption and formatting information as used by ITM but you can override this on an attribute-by-attribute basis.
This statement defines the attribute names from the query whose data that should be used to create variables of the same name as the attribute when the row of data is selected as you navigate forward.
Any attribute name you specify here must also be specified in the QUERY statement.
The SORTCOLS statement specifies the attributes that should be indexed so that the rows of data in a TYPE=SUMMARY sub panel can be sorted by the user.
Since there is an overhead associated with building these indexes, especially for large row sets, it is recommended that you keep the number of sortable attributes to the minimum required to enable the user to perform the task at hand.
Any attribute name you specify here must also be specified in the QUERY statement.
The ZOOMSCOLS statement specifies the attributes that the user can ‘zoom’ on by placing the cursor on the attribute name for a detail sub panel, or the data for a summary sub panel, and the target workspace.
Any attribute name you specify here must also be specified in the QUERY statement and must also be specified in the DISPLAYCOLS statement.
The ACTION statement only applies to summary sub panels. Each instance of an ACTION statement defines the selection character that must be entered to invoke the associated action, the text to be displayed when the user inputs a / in the selection field to display the available options, the target workspace member name when this option is selected and for one entry, the DEFAULT option to indicate that this is the default option to be taken if the user just places the cursor in the input field and presses enter without entering a selection character.
A typical definition might look like this:
ACTION=RTYPE(S,”CICS Bottleneck Detail”,KCPBOTD,DEFAULT)
ACTION=RTYPE(T,”CICS Tasks Waiting for Resource”,KCPBOTT)
The RTYPE value (in this example) is the name of the attribute that the input field is to be displayed next to. Currently this is not used. There is always only one selection field and it is to the left of the first attribute that is displayed for each row.
Basic Workspace Customization
There are a few simple things that you can do to customize workspaces and sub panels.
Rearrange Displayed Attributes
For summary panels, you may prefer to see different attributes on the left of the tabular display so that that they are more rapidly visible without having to scroll the sub panel to the right to see them.
In the DISPLAYCOLS entry, each attribute should be followed by a comma and the entire string enclosed in quotes. For example:
Change or Add Captions
You can override the default caption extracted from the ITM Attribute Group definition by changing an existing caption override or adding a CAPTION entry after the attribute name. For example:
SOS(CAPTION=”Short On Storage”)’
Split a Sub Panel into multiple Sub Panels
For summary sub panels, which display the data as a scrollable table, if the number of attributes specified in the DISPLAYCOLS entry is larger than the screen width can display then the user will need to scroll left and right to see them all.
If you prefer you could split the displayed data into two sub panels so that you can see data that is currently off screen to the right, on a second sub panel below the first.
The process is fairly straightforward.
- Within the workspace, make a copy of the sub panel you want to split so that the new copy follows the existing one.
- Change the QUERY statement so that it reads as follows:
This will avoid the same query from being issued twice. Instead this sub panel will reuse the result set from the previous sub panel.
- Edit the DISPLAYCOLS statement in each sub panel so that it displays the required attributes.
Convert a Detail Sub Panel to a Summary Sub Panel
A detail sub panel can occupy multiple lines on the screen. You might prefer to display the data as a summary style sub panel and have the user scroll left and right to see the additional data.
This is a simple as changing the sub TYPE=DETAIL entry in the sub panel header so that it reads TYPE=SUMMARY.
You may also need to delete or comment out any LINES entry in the sub panel header.
So for example, this:
Zoom style navigation will still work as it did before. You may also be able to add action style navigation to the same workspaces as the zoom navigation by adding appropriate ACTION statements to the sub panel entry.
For Example, if the ZOOMCOLS entry for the sub panel is:
Then you ‘may’ be able to add the following to the sub panel so that you can navigate using action characters or the action menu:
ACTION=’CICSNAME(S,”CICS Regions Overview”,KCPRGNO,DEFAULT)
ACTION=’CICSNAME(T,”CICS Task Summary”,KCPTASS)
When the ZOOMCOLS definition for a column takes the user to a silent workspace, particularly one that runs a REXX exec then you may find it does not work as expected. However for basic navigation to another workspace this conversion ‘should’ work fine.
Convert a Summary sub Panel to a Detail Sub Panel
You can only convert a summary sub panel to a detail sub panel if the query associated with it only ever returns a single row of data. If the query returns multiple rows, only the FIRST row of data that is returned will be displayed.
The process is pretty much the reverse of the above.
- Change TYPE=SUMMARY to TYPE=DETAIL
- Add a COLUMNS=n entry to the header if you want the display to be more than a single column.
- Add a ZOOMCOLS entry and specify the attribute name that you want to zoom on and the target workspace member name.
- Delete or comment out any ACTION statements.
This article will describe how to customize the basic features of the IBM OMEGAMON XE Enhanced 3270 User Interface (E3270UI).
When a user logs on to the E3270UI, the datasets allocated the RKOBPROF DD in the Tivoli OMEGAMON Manager (TOM) JCL are for a profile member. The search order is as follows:
· A member with the same name as the userid that is logging on.
· A member named CUASITE.
· A member named KOBCUA.
Typically, the datasets allocated to the RKOBPROF DD are hlq.UKOBDATF and either hlq.TKOBDATF or hlq.RKOBDATF. User modified and created members should be placed in the UKOBDATF dataset. You should not modify the TKOBDATF or RKOBDATF datasets since any changes made will be lost if you apply service to the product install or run time environment.
KOBCUA is the product provided default profile. You can either copy this from the TKOBDATF or RKOBDATF dataset to the UKANDATF dataset and make any changes to it there, or use it as a model to create CUASITE and userid specific members within the UKOBDATF dataset.
Parts of the Logon Profile Member
The logon profile member is split into a number of sections as follows:
The LOCALEID entry controls a couple of things as follows:
· It defines the suffix of the KOBxxxx locale member in the RKOBPROF concatenation. The default value selects the KOBENUS member.
· The first three characters (ENU in the default case) specify the last three characters of the RKANWxxx DD card used to load workspaces from. The default setting causes workspaces to be loaded from the RKANWENU DD. This enables you to create language specific workspaces for specific users and have them loaded from a different workspace DD for those users whose logon profile directs them to that DD.
The CUACOLOR section defines the colors used for the various elements of E2370UI workspaces.
The seven standard 3270 color names can be used:
WHITE, YELLOW, TURQUOISE, BLUE, GREEN, PINK, RED
The CUASTATUS section controls the colors used for the status lights triggered by thresholding.
The CUAPFKS section controls the assignment of commands to PF and PA keys.
The FIRSTWS option in the CUANAV section specifies the member name of the workspace that is displayed after the user initially logs on to the E3270UI.
The CUADATA section specifies the name of the hub TEMS that queries are to be directed to. It can also specify the IP address and port number which may be required if there are multiple hubs in the environment with duplicate names.
The TOM will select DRAs based on the hub name specified here since the DRA must be in an ITM environment that can communicate with the specified hub.
The KOBxxxx LOCALE member
The locale member suffix is specified by the LOCALEID keyword of the logon profile. The product provided default member is KOBENUS.
The LOCALE section defines locale specific settings such as the data format and currency symbols.
ACTIONBAR sections within the locale member define the tool bar text and actions that appear at the top of the E3270UI workspace.