Long-Name Files and USS Supported Files

ce18
Long Element names are greater than 10 and less than 256 characters; short Element names are less than or equal to 10 characters. Path names can be 768 characters. The following are supported for mixed-case long-named Elements and for USS path and file names added from UNIX System Services (USS) supported files systems.
  • Enter or view Elements and perform the Element display options (B, C, H, M, and S) on ISPF panels for classic and Quick Edit
    Endevor
    .
  • Add, Update, and Retrieve actions that are performed in foreground and batch.
  • Type definitions support USS directories as base, source output, and include libraries.
  • Processor symbols for long name Elements and USS directories.
  • USS path and file name support for the CONWRITE and CONDELE utilities.
  • For USS file names, all IBM supported characters are supported by
    Endevor
    . For Element names, the allowable characters are: blank, ., $, -, _, #, @, a-z, {, A-Z, 0-9. You can add any USS File into
    Endevor
    or retrieve an Element to any USS file name. However, if the USS file name is not a valid Element name, you must specify a valid name for the Element when you use the Add action. When using the Retrieve action, you can specify a USS file name that is different from the Element name.
Support Depends on User Interface
Long name support varies according to the ISPF interface you are using.
  • ISPF panels for classic or Quick Edit
    Endevor
    You can enter or view mixed-case long-named Elements and perform the Element display options (B, C, H, M, and S) on long-named Elements.
    For more information about support for long-named Elements, see Long-Named Elements.
  • Batch (SCL), API,
    Change Manager Enterprise Workbench
    , Eclipse-Based UI, and Web Services User-Written Client Programs
    You can enter or view mixed-case long-named Elements.
USS path and file name support is unavailable for the following functions:
  1. CONLIST, CONRELE, or other utilities
  2. The processor keyword MONITOR=
  3. The processor keyword FOOTPRNT.
Adding and Retrieving Long Name Elements
These file Types are used to add Elements to
Endevor
or retrieve Elements from
Endevor
:
  • DSN files-
    Endevor
    supports base and source output libraries:
    • PDS, PDSE
    • ELIB
    • Panvalet
    • Librarian
    • USS
  • USS path and file names
    Elements can be retrieved from
    Endevor
    and saved as a DSN member or as a file in the USS directory.The Element name's characteristics limit which file Type can be used as the target of the retrieve action, as shown in the following table:
Element Name Characteristics
USS
DSN
Long-alphanumeric mixed case and @, $, #,., -,_
Yes
No
Short-alphanumeric mixed case and @, $, #,., -,_
Yes
No
Short-alphanumeric upper case and @, $, #,., -,_
Yes
Yes
USS Directories and
Endevor
Libraries
Some
Endevor
libraries can be located on a Unix System Services file system. Currently, the only supported libraries are:
  • Base
  • Source output
  • Include
The following table lists the
Endevor
libraries that can be located on USS file systems:
Library
z/OS
USS
Master Control Files
Yes
No
Package data set
Yes
No
Base libraries
Yes
Yes
Delta libraries
Yes
No
Processor output libraries
Yes
No
Source output libraries
Yes
Yes
Processor load libraries
Yes
No
Processor listing libraries
Yes
No
Endevor
listing libraries
Yes
No
Include libraries
Yes
Yes
Processors can write outputs to USS directories. In addition, ensure that the maximum record size associated with the USS file can be accommodated by the delta library specified on the Type definition.
USS Directories and Type Definitions
If a USS file is to be used as a base file, no Types should share this file name. Element registration (using Processor Group Output Types) should be used to enforce the segregation across Types.
When designating USS directories as base, source output, or include libraries in Type definitions, you can use site symbolics,
Endevor
symbolics, or text to construct paths. As with
Endevor
or user symbolics, the site symbolics are resolved at runtime.
The USS RECFM Field
USS files are data streams. The USS RECFM field specifies a record delimiter used to emulate records. To emulate records, there must be a record delimiter. This is the purpose of the USS RECFM field.
The change of a delimiter for Types with existing Elements may make these Elements unusable for Retrieve actions.
USS RECFM (COMP/CR/CRLF/CRNL/F/LF/NL/V)
Identifies the record delimiter used in a USS file. A record delimiter is necessary due to the nature of USS files. USS files contain one large data stream. Therefore, a delimiter is used to identify individual records within that data stream.
This is also true for Elements associated with a Type defined as text (Data Format=T). When the Element is transferred from
Endevor
to
Change Manager Enterprise Workbench
or any other client application that uses
Endevor
WebServices. These programs recognize and append the delimiter for the exchanged records. However, these delimiters are then translated from EBCDIC to the target code page. When the Element is transferred to
Endevor
, all delimiters are removed before translation. The one exception is where two delimiters appear consecutively, in which case a single space is inserted to avoid creating zero length records.
If a delimiter is not specified, the system defaults to NL.
The change of a delimiter for Types with existing Elements may make these Elements unusable for Retrieve actions.
Acceptable delimiter values are the following:
  • COMP
    Variable length records compressed by
    Endevor
    .
  • CR
    Carriage return. The hex value is x'0D' (and also x'0D' in ASCII).
  • CRLF
    Carriage return \ line feed. The hex value is x'0D25' (or x'0D0A' in ASCII). This is the default delimiter used on the Windows platform.
  • CRNL
    Carriage return \ new line. The hex value is x'0D15' (or x'0D0A' in ASCII).
  • F
    Fixed Length. When the Type is specified as fixed length,
    Endevor
    does not expect or use any delimiters found in the file. This option should also be used for
    Stream data
    especially in binary Elements, to allow the native file system (ASCII or EBCDIC) delimiters to remain unchanged.
  • LF
    Line feed. The hex value is x'25' (or x'0A' in ASCII).
  • NL
    Default. New line character. The hex value is x'15' (or x'0A' in ASCII). This is the delimiter used by the OEDIT and OBROWSE editors. It is also the default delimiter on Unix platforms and is supported in several Windows editor environments, making it a good choice for interoperability.
  • V
    Variable. The first four bytes of the record contain the RDW (record descriptor word). The RDW contains the length of the entire record, including the RDW.
The maximum record length is 32000 bytes.
File Permissions Given to Output UNIX Files
The file permissions given to output UNIX files are dependent on various factors as described next:
  • Endevor
    managed files (base files and source output files)
    • If option ENABLE_ALTID_USS_SECURITY is enabled, then the file permissions specified in that option are used.
    • Otherwise, the UNIX permissions of 777 (a=rwx) are set.
  • Other output files
    • Files written to by the RETRIEVE command
      • If the target file exists, its existing file permissions are kept.
      • If the target file does not exist, the UNIX permissions of 777 a=rwx are set.
      • The directory structure for the target output file must give all users execute access.
    • Files written to by CONWRITE during processor execution.
      • If the DD statement for the file contains file permissions ons (PATHMODE) values, those permissions are used.
      • If the DD statement does not contain file permission and if the file is an existing file, the existing permissions are kept.
      • If the DD statement does not contain file permission and If the file does not exist, the UNIX permissions of 777 (a=rwx) are set.
      • The directory structure for the target output file must give all users execute access.
    • Files written by the ENUSSUTL utility, which collects package backout information for USS processor output files.
Concurrent Access ENQUEUE Scheme
To manage concurrent use of the
Endevor
footprint file when it is in a z/OS UNIX directory,
Endevor
issues an ENQUEUE for the file.
The ENQ QNAME and RNAME follow the convention used by ISPF Edit and OEDIT as documented in the IBM
ISPF Planning and Customization
manual. The QNAME is SPFEDIT. RNAME is a 12-byte value consisting of the 4-byte Inode#, the 4-byte Device# and a 4-byte sysplex indicator. The sysplex indicator is x'00000001' if z/OS UNIX is in a sysplex (OextSysplexActv is set ON) or x'00000000' if z/OS UNIX is not in a sysplex (OextSysplexActv is set OFF). The ENQ scope is set to SYSTEMS if z/OS UNIX is in a sysplex, otherwise it is set to SYSTEM.
USS Supported Files and the Alternate ID
When using a USS base library,
Endevor
source management accesses the library using the alternate ID.
Endevor
also uses the alternate ID when it accesses a USS source output library in the
Endevor
reserved processors BASICGEN and BASICDEL.
The security context of a processor step is determined by the following factors:
  • ALTID keyword
    The security context used for USS file access in processor steps is determined by the ALTID keyword. Processors can run under either the credentials of the user, or under the Alternate ID, so that USS outputs (created, copied, compiled, and so on) will have the Alternate ID as the owner or group owner. For more information about Alternate ID support, see Data Set Security.
  • PATHOPTS=(OCREAT)
    Any USS data sets created in processor steps using PATHOPTS=(OCREAT) are created using the security context of the user ID, prior to the invocation of the processor program. When used in the processor step, these data sets are opened using the security context of the processor step.
  • EXEC PGM=BPXBATCH
    The security context of a processor step executing the IBM USS utility program BPXBATCH depends on the following factors:
    • Whether BPXBATCH runs a shell script (PARM=’SH’) or directly executes an executable file (PARM=’PGM’).
      We recommend BPXBATCH be invoked directly as processor step.
    • The settings of the Environment variables _BPX_BATCH_SPAWN and _BPX_SHAREAS.
    The following table shows combinations of these parameters and settings with the resulting security context of the processor step executing BPXBATCH.
BPXBATCH parameter
_BPX_BATCH_SPAWN
_BPX_SHAREAS
Security context
SH
ANY
ANY
Alternate ID
PGM
NO
n/a
Alternate ID
PGM
YES
NO
Alternate ID
PGM
YES
YES
User ID
  • BPXBATSL, BPXBATA2 and BPXBATA8
    These programs always run under the context of the user ID, because they process requests in the same manner as the last row in the prior table (_BPX_BATCH_SPAWN=YES, and _BPX_SHAREAS=YES).
  • BPXBATCH in an IKJEFT01 processor step
    We do not recommend the use of BPXBATCH in an IKJEFT01 step, because the results can be unpredictable.
    Whether BPXBATCH invoked by a CLIST or REXX in a processor step executing IKJEFT01 executes under the context of the alternate ID depends on the following two
    additional
    factors:
    • Whether or not a LGNT$$$I swap was performed prior to the invocation of BPXBATCH.
    • Whether or not a prior USS service call was made in the job step prior to the BPXPBATCH call. For example, the prior USS service call could occur when a USS Base or Source Output Library was used during the
      Endevor
      job step, or when a shell script was executed in this or any prior
      Endevor
      action.
    The following table shows the security context results from these two additional factors when calling BPXBATCH from a processor step that executes IKJEFT01:
LGNT$$$I swap performed
Prior USS Service call made
Security context
Yes
No
Alternate ID
Yes
Yes
Failure
No
No
User ID
No
Yes
User ID