JAR entry (target and distribution zone)

The JAR entry describes a Java™ Archive (JAR) file that resides in a UNIX file system and a distribution library. A JAR entry is created the first time a SYSMOD is installed that contains a ++JAR MCS.

Subentries

These are the subentries for the JAR entry as they appear in the LIST output:

name

is the name of the Java ARchive element represented by the JAR entry.

The name can contain 1–8 uppercase alphabetic, numeric, or national ($, #, @) characters.

DISTLIB

specifies the ddname of the distribution library for the JAR element.

The UCL operand is DISTLIB(ddname).

The ddname can contain any uppercase alphabetic, numeric, or national ($, #, @) character, and can be 1–8 characters long.
The DISTLIB subentry is required. Without it, SMP/E cannot process any changes for the JAR element.

FMID

identifies the functional owner of this JAR element. The functional owner is the last function SYSMOD that replaced this JAR element.

The UCL operand is FMID(sysmod_id).

The SYSMOD ID must contain 7 uppercase alphabetic, numeric, or national ($, #, @) characters.

JARPARM

specifies a character string that is to be passed to the jar command as an option string when updating the JAR file. The maximum length of this character string is 300 bytes of data.

Any jar command options specified here will be passed to the jar command in addition to the options supplied by SMP/E, which are uvf (u indicates that the JAR file is to be updated, v produces verbose jar command output, and f indicates that the JAR file to be updated is specified on the command line rather than through stdin).

Only those jar command options that require only the option indicator to be specified are supported in the JARPARM entry, such as 0 and M. Options requiring additional input over and above the option indicator are not supported. Examples of unsupported options are the m and -C options. If such options are specified, the jar command will likely fail, since SMP/E does not prohibit their use.

LASTUPD

identifies the cause of the last change to this JAR entry.

The UCL operand is LASTUPD(value). This subentry can contain one of the following values:

UCLIN: indicates that the change was made as a result of UCLIN processing.
sysmod-id: indicates that the change was made during the installation of the indicated SYSMOD.
The SYSMOD ID must contain 7 uppercase alphabetic, numeric, or national ($, #, @) characters.

LASTUPDTYPE

indicates how the entry was last changed.

The UCL operand is LASTUPDTYPE(value). This subentry can contain one of the following values:

ADD: The entry was added.
UPD: The entry was updated.

LINK

specifies a list of alternative names by which this JAR element can be known in the UNIX file system.

In LIST output, linknames are always enclosed in single apostrophes. If an apostrophe is part of a linkname, it is always shown as two consecutive apostrophes in LIST output.

The UCL operand is LINK(linkname…).

The linkname can be from 1 to 1023 characters.
A linkname can be enclosed in single apostrophes ('). A linkname must be enclosed in single apostrophes if any of the following is true:
- The linkname contains lowercase alphabetic characters.
- The linkname contains a character that is not uppercase alphabetic, numeric, national ($, #, or @), slash (/), plus (+), hyphen, period, or ampersand (&).
- The linkname spans more than one line in the control statement.
The single apostrophes used to enclose a linkname (the delimiters) do not count as part of the 1023-character limit.
Any apostrophes specified as part of a linkname (not the delimiters) must be doubled.
Double apostrophes count as two characters in the 1023-character limit.
The linkname can include characters X'40' through X'FE'.

PARM

specifies a character string that is to be passed to the copy utility as an execution-time parameter. The maximum length of this character string is 300 bytes of nonblank data. If any blanks are specified in the PARM value, they are deleted by SMP/E during processing and do not count toward the 300-byte maximum.

The UCL operand is PARM(character_string).

PARM is an optional operand.
The character string can be entered free-form, without regard to blanks (which are compressed out of the string), and can span multiple 80-byte records.
If parentheses are specified in the PARM value, there must always be a pair (left and right); otherwise, the results are unpredictable.

RMID

identifies the last SYSMOD that replaced this JAR element. Any subsequent SYSMOD that modifies this JAR element must have defined a relationship (such as PRE or SUP) with this SYSMOD.

The UCL operand is RMID(sysmod_id).

The SYSMOD ID must contain 7 uppercase alphabetic, numeric, or national ($, #, @) characters.
If RMID is not specified but FMID is, SMP/E sets the RMID value to the specified FMID.

SHSCRIPT

specifies a UNIX shell script to run when this JAR element is copied to (or deleted from) a directory in the UNIX file system.

The UCL operand is SHSCRIPT(scriptname). This subentry optionally contains one or both of the following values, which specify the point in SMP/E processing when the shell script is run:

PRE: The shell script is run before the JAR element is copied to a UNIX file system directory.
POST: The shell script is run after the JAR element is copied to a UNIX file system directory.

POST is the default; the shell script is run after the JAR element is copied to the directory.

SYMLINK

specifies a list of one or more symbolic links, which are file names that can be used as alternate names for referring to this JAR element in the UNIX file system. Each symbolic link name listed here is associated with a path name listed in the SYMPATH entry. See the description of the SYMPATH entry for more information about how the symbolic link names and path names are associated.

The UCL operand is SYMLINK(symlinkname…).

A JAR entry that contains a SYMLINK entry must contain a matching SYMPATH entry. SMP/E will reject any UCLIN command that would violate this condition.
A symbolic linkname can be from one to 1023 characters. Any characters in the range X'40' through X'FE' may be specified.
A symbolic linkname can be enclosed in single apostrophes ('). A symbolic linkname must be enclosed in single apostrophes if any of the following is true:
- The symbolic linkname contains lowercase alphabetic characters.
- The symbolic linkname contains a character that is not uppercase alphabetic, numeric, national ($, #, or @), slash (/), plus (+), hyphen, period, or ampersand (&).
- The symbolic linkname spans more than one line in the control statement.
The single apostrophes used to enclose a symbolic linkname (the delimiters) do not count as part of the 1023-character limit.
Any apostrophes specified as part of a symbolic linkname (not the delimiters) must be doubled. Double apostrophes count as two characters in the 1023-character limit.

SYMPATH

specifies a list of one or more pathnames that are associated with symbolic links identified by the SYMLINK operand. The first pathname in the SYMPATH operand is associated with the first symbolic link in the SYMLINK operand, the second pathname with the second symbolic link, and so on. If there are more symbolic links listed than there are pathnames, then the last listed pathname is used for the remaining symbolic links. If more pathnames are specified than symbolic linknames, then the excess pathnames (at the end of the list) are ignored. The UCL operand is SYMPATH(sympathname…).

A JAR entry that contains a SYMPATH entry must contain a matching SYMLINK entry. is specified, otherwise it must be omitted.
A symbolic pathname can be from one to 1023 characters. Any characters in the range X'40' through X'FE' may be specified.
A symbolic pathname can be enclosed in single apostrophes ('). A symbolic pathname must be enclosed in single apostrophes if any of the following is true:
- The symbolic pathname contains lowercase alphabetic characters.
- The symbolic pathname contains a character that is not uppercase alphabetic, numeric, national ($, #, or @), slash (/), plus (+), hyphen, period, or ampersand (&).
- The symbolic pathname spans more than one line in the control statement.
The single apostrophes used to enclose a symbolic pathname (the delimiters) do not count as part of the 1023-character limit.
Any apostrophes specified as part of a symbolic pathname (not the delimiters) must be doubled. Double apostrophes count as two characters in the 1023-character limit.

SYSLIB

specifies the ddname of the "target library" within a UNIX file system for the JAR element.

The UCL operand is SYSLIB(ddname).

Only one SYSLIB value can be specified.
The ddname can contain any uppercase alphabetic, numeric, or national ($, #, @) character, and can be 1 to 8 characters long.
The SYSLIB subentry is required. Without it, SMP/E cannot process any changes for the JAR element.

UMID

identifies all of the SYSMODs that have updated this JAR file since it was last replaced. Any subsequent SYSMOD that updates or replaces this JAR file must have a defined relationship (such as PRE or SUP) with all SYSMODs in the UMID subentry.

LIST Examples

To list all the JAR entries in a particular zone, you can use the following commands:

SET      BDY(TGT1)      /* Set to zone.             */.
LIST     JAR            /* List all JAR entries.    */.

To list specific JAR entries, you can use these commands:

SET      BDY(TGT1)      /* Set to zone.             */.
LIST     JAR(JAREL1,    /* List only these two      */
             JAREL2)    /* entries.                 */.

The format of the LIST output for each JAR entry is the same for both of these commands. The only difference is the number of JAR entries listed.

Figure 1 is an example of LIST output for a JAR entry.

Figure 1. JAR entry: sample LIST output

PAGE nnnn  - NOW SET TO zzzzzz ZONE nnnnnnn  DATE mm/dd/yy TIME hh:mm:ss SMP/E 36.nn SMPLIST OUTPUT

SMPPTS        MCS ENTRIES


  NAME

ABCTTT        LASTUPD         = HABC100  TYPE=ADD                        
              LIBRARIES       = DISTLIB=AABCBIN   SYSLIB=SABCBIN         
              FMID            = HABC100                                  
              RMID            = HABC100                                  
              UMID            = OW12345   OW54321   OW34567              
              SHSCRIPT        = ABCSCRPT,PRE,POST                        
              PARM            = PATHMODE(0,6,4,4)                        
              JARPARM         = 0M                                       
              SYMLINK         = '../../../../../usr/lib/TicTacToe.jar'   
              SYMPATH         = '../../usr/lpp/ttt/bin/TicTacToe.jar'    
              LINK            = '../TicTacToe.jar'

By specifying the FORFMID operand, you can reduce the number of JAR entries listed. When FORFMID is specified, SMP/E lists a JAR entry only if its FMID matches one of the FMIDs specified on the FORFMID operand. For example, to list JAR entries whose FMIDs either are defined in FMIDSET JAR or are JARFUNC, you can use these commands:

SET      BDY(TGT1)          /* Set to target zone.      */.
LIST     JAR                /* List all JAR entries    */
         FORFMID(JAR        /* for the JAR FMIDSET      */
                 JARFUNC)   /* and FMID JARFUNC.        */.

You can use the LIST command to find out the names of all SYSMODs that have modified a JAR element. To include the names of these SYSMODs in the LIST output you can use the XREF operand, as shown in these commands:

SET      BDY(TGT1)          /* Set to requested zone.   */.
LIST     JAR                /* List all JAR entries    */
         XREF               /* and related SYSMODs.     */.

Note:

XREF can be used either in mass mode or in select mode.
SMP/E obtains the data included for the XREF operand by checking all the SYSMOD entries for subentries for this JAR element. Because this data is not contained in the JAR entry itself, you cannot use UCLIN to change it in the JAR entry.

Figure 2 is an example of the LIST output produced when the XREF operand is used.

Figure 2. JAR entry: sample LIST output when XREF is specified

PAGE nnnn  - NOW SET TO zzzzzz ZONE nnnnnnn  DATE mm/dd/yy TIME hh:mm:ss SMP/E 36.nn SMPLIST OUTPUT
 
TGT1    JAR     ENTRIES               
                                                                               
   NAME 
                                                                                 
 ABCTTT    LASTUPD         = JAR0001  TYPE=ADD                                   
           LIBRARIES       = DISTLIB=DLIB3     SYSLIB=SLSRBIN                    
           FMID            = JAR0001                                             
           RMID            = JAR0001                                             
           PARM            = PATHMODE(0,7,7,5)                                   
           JARPARM         = 0M                                                  
           LINK            = '../TicTacToe.jar'                                  
           UMID            = PT00002                                             
           SYSMOD HISTORY  = SYSMOD   TYPE       DATE   MCS       ---------- STAT
                             JAR0001  FUNCTION  07.100  JAR       APP            
                             PT00002  PTF       07.100  JARUPD    APP

UCLIN Examples

You can use the ADD, REP, and DEL UCL statements to change subentries in the JAR entry. After the UCLIN changes are made, the JAR entry must contain at least the following subentries:

DISTLIB
FMID
RMID
SYSLIB

Otherwise, there is not enough information in the entry to process the element. If any of these subentries are missing, SMP/E does not make the requested UCL updates to the entry, and the entry remains as it was before the UCL command.

The following examples are provided to help you use the JAR entry:

   Example 1                                                            
                                                                        
     SET BDY(TGT)                         /* Set to target zone        */.
     UCLIN                                /* Start UCLIN processing    */.
       ADD JAR(ABCTTT) JARPARM(0M)        /* Add JARPARMs              */.
     ENDUCL                               /* End UCLIN processing      */.
                                                                        
   Example 2                                                            
                                                                        
     SET BDY(TGT)                         /* Set to target zone        */.
     UCLIN                                /* Start UCLIN processing    */.
       REP JAR(ABCTTT) JARPARM(M)         /* Replace with new JARPARMs */.
                       UMID(OW12345,OW54321) /* and new UMIDs          */.
     ENDUCL                               /* End UCLIN processing      */.
                                                                        
   Example 3                                                            
                                                                        
     SET BDY(TGT)                         /* Set to target zone        */.
     UCLIN                                /* Start UCLIN processing    */.
       DEL JAR(ABCTTT) JARPARM()          /* Delete JARPARMs           */.
     ENDUCL                               /* End UCLIN processing      */.

In the first example, a string of options is added to the JARPARM subentry in the JAR entry ABCTTT. In the second example, the existing JARPARM subentry value for ABCTTT is replaced with a new value and the UMID subentry list is replaced with a new list of values. In the third example, the JARPARM subentry is deleted from the JAR entry for entry name ABCTTT.

UNLOAD Examples

To dump all the JAR entries in UCL format, you can use the UNLOAD command:

SET      BDY(TGT1)      /* Set to zone.             */.
UNLOAD   JAR            /* Unload all JAR entries.  */.

To dump specific JAR entries, you can use these commands:

SET      BDY(TGT1)      /* Set to zone.             */.
UNLOAD   JAR(JAREL1,    /* Unload only these two    */
             JAREL2)    /* entries.                 */.

The format of the UNLOAD output for each JAR entry is the same for both of these commands. The only difference is the number of JAR entries unloaded.

Figure 3 is an example of the output created by the UNLOAD command for a JAR entry:

Figure 3. Example UNLOAD output for JAR entry

   UCLIN .                                                              
   REP       JAR             ( ABCTTT   )                               
             LASTUPD         ( HABC100 )                                
             LASTUPDTYPE     ( ADD )                                    
             DISTLIB         ( AABCBIN  )                               
             SYSLIB          ( SABCBIN  )                               
             FMID            ( HABC100 )                                
             RMID            ( HABC100 )                                
             UMID            ( OW12345   OW54321   OW34567 )            
             SHSCRIPT        ( ABCSCRPT,PRE,POST )                      
             PARM            ( PATHMODE(0,6,4,4) )                      
             JARPARM         ( 0M )                                     
             SYMLINK         ( '../../../../../usr/lib/TicTacToe.jar' ) 
             SYMPATH         ( '../../usr/lpp/ttt/bin/TicTacToe.jar' )  
             LINK            ( '../TicTacToe.jar' )                     
                             .                                          
   ENDUCL.

By specifying the FORFMID operand, you can reduce the number of JAR element entries unloaded. When FORFMID is specified, SMP/E unloads an JAR element entry only if its FMID matches one of the FMIDs specified on the FORFMID operand. For example, to unload JAR element entries whose FMIDs either are defined in FMIDSET JAR or are JARFUNC, you can use these commands:

SET      BDY(TGT1)          /* Set to target zone.             */.
UNLOAD   JAR               /* Unload all JAR element entries */
         FORFMID(JAR       /* for the JAR FMIDSET            */
                 JARFUNC)   /* and FMID JARFUNC.               */.