You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: endevor/Package-Shipping-Model-and-Script-Examples/README.md
+75-34Lines changed: 75 additions & 34 deletions
Original file line number
Diff line number
Diff line change
@@ -1,21 +1,30 @@
1
1
# Package Shipping Model and Script examples
2
2
3
-
There are many challenges when working with Endevor's package shipping.
4
-
5
-
One Package shipment can submit up to 4 jobs, depending on the transmission tool used. If you are shipping to and from multiple sites, it becomes difficult to track the site names and packages to the job outputs.
6
-
7
-
There are many parts to the package shipping process. It can be confusing to know where to insert the new code you want to include.
8
-
9
-
Objects from the Endevor CSIQSENU library are standard [IBM File Tailoring Skeletons](https://www.ibm.com/docs/en/zos/3.1.0?topic=reference-defining-file-tailoring-skeletons), whereas objects from Endevor's CSIQOPTN libary use a syntax that is unique to package shipping.
3
+
There are a few challenges when working with Endevor's package shipping.
4
+
One Package shipment can submit up to 4 jobs, depending on the transmission tool used. If you are shipping to and from multiple sites, there are some things you can do to make it easier to track job outputs to the site names and packages that spawned them.
10
5
11
6
Items in this folder may help with these challenges, and to complement the material found in [Shipping and Post Ship Scripts demysfied](https://community.broadcom.com/blogs/joseph-walther/2023/11/27/package-shipping-and-post-ship-scripts-de-mystifie). Included are:
12
7
8
+
- Reminders for Setting up Package Shipments
13
9
- Items to comment your package shipping jobs - a first step in keeping track of package shipping objects
10
+
- Member inclusions
14
11
- Miscellaneous tips and techniques
15
12
13
+
## Reminders for Setting up Package Shipments
14
+
15
+
Objects from the Endevor CSIQSENU library are standard [IBM File Tailoring Skeletons](https://www.ibm.com/docs/en/zos/3.1.0?topic=reference-defining-file-tailoring-skeletons), whereas objects from Endevor's CSIQOPTN library use a syntax that is unique to package shipping. Here are some recommended steps for setting up Package Shipments:
16
+
17
+
- Check the RJCLROOT value on your Defaults table. Techdoc says...
18
+
19
+
"The generation of the remote copy and delete job stream is controlled by the C1DEFLTS specification for RJCLROOT keyword. RJCLROOT specifies the member root for the package ship remote JCL model."
20
+
21
+
- If you modify any of the CSIQSENU or CSIQOPTN members, consider placing them into one or two override libraries, separate from the Endevor product libraries. Then, make sure your override libraries are concatenated in your C1BMXJOB, or whatever equivalent you are using. Where you see a reference to a CSIQOPTN or a CSIQSENU library, concatenate an override library above the one that is there. See also the **Tips and Techniques** section below for more.
22
+
23
+
- Comment the members you modify, so that when you are viewing package shipment jobs, you will be able to easily find the contributing objects that created them.
24
+
16
25
## Commenting Package Shipment Jobs
17
26
18
-
Generous commenting of your package shipping objects helps you to connect jobs to their originations. Remote and confirmation jobs might be commented this way, giving you backward pointers to the origin of each package shipment.
27
+
Generous commenting of your package shipping objects helps you to connect jobs to their originations. Remote and confirmation jobs might be commented this way (after variable substitution), giving you backward pointers to the origin of each package shipment.
Job steps may be commented this way to name the package shipment object that contributed the step to the JCL:
40
+
Comment your Job steps to name the package shipment object that contributed the step to the JCL:
32
41
33
42
34
43
Command ===> Scroll ===> CSR
@@ -54,7 +63,7 @@ Job steps may be commented this way to name the package shipment object that con
54
63
55
64
Where QBOXB, C1BMXRCN are package shipping members and/or elements in your Endevor Admin area.
56
65
57
-
Package Shipping variables are made available early in the shipment process. If you capture them at the appropriate time you can use them within the shipping objects to better comment, and to enhance functionality. Objects in this folder serve as examples in capturing and leveraging variables such as those listed here.
66
+
Package Shipping variables are made available early in the shipment process. If you capture them at the appropriate time you can use them within the remaining shipping objects to better comment, and to enhance functionality. Objects in this folder serve as examples in capturing and leveraging variables such as those listed here.
58
67
59
68
- VDDHSPFX - Host staging dataset name prefix
60
69
- VDDRSPFX - Remote staging dataset name prefix
@@ -64,39 +73,79 @@ Package Shipping variables are made available early in the shipment process. If
64
73
- VNB6TIME - Six character shipping Time
65
74
- VPHPKGID - Package ID
66
75
67
-
See the **)REXX** and **)ENDREXX** blocks within the **C1BMXIN** member as examples for capturing package shipment variables. Paired with the **@DBOX** member, **C1BMXIN** is able to leverage additional variables whose values are applicable to only one host or sending site.
76
+
See the **)REXX** and **)ENDREXX** blocks within the **C1BMXIN** member as an example for capturing package shipment variables.
77
+
The combination of the **@DBOX** and **C1BMXIN** members gives you the ability to capture shipping-time variables that you can use across your shipping objects. See more in the topic on **Multiple Endevors**.
78
+
68
79
69
-
### Skeleton / Model / Script example members for commenting
80
+
### Skeleton / Model / Capture and re-use of shipping variables
70
81
71
-
Members in this folder that help with commenting include:
82
+
Members in this folder show how you can capture values for shipping variables and re-use them.
72
83
73
-
__C1BMXIN.skl__ is a version of the C1BMXIN skeleton found in your CSIQSENU library. This version captures values for some of the package shipping variables, and makes it possible for them to be available in your shipping JCL. Shipments for all transmission methods use the C1BMXIN member. The example uses Table Tool in a step named TAILOR to capture and expand variables for subsequent shipping jobs.
84
+
__C1BMXIN.skl__ is a version of the C1BMXIN skeleton found in your CSIQSENU library. This version captures values for some of the package shipping variables, and makes it possible for them to be available in your shipping JCL. Shipments for all transmission methods use the **C1BMXIN** member. The example uses Table Tool in a step named TAILOR to capture and expand variables for subsequent shipping jobs.
74
85
75
-
The example tailors the content of C1BMXFTC, which is the job submitted for Netview FTP (or IBM FTP) commands. The inclusion or exclusion of the C1BMXFTC references in your version might depend on your transmission utility.
86
+
The example tailors the content of C1BMXFTC, which Endevor builds for Netview FTP (or IBM FTP) commands. The inclusion or exclusion of the C1BMXFTC references in your version might depend on your transmission utility. You will need to tailor outputs for the transmission tool you are using.
76
87
77
88
__#RJICPY1.skl__ is a version of the #RJICPY1 showing commented steps.
78
89
79
-
The edit maccro __JCLCOMMNT__ can help insert comments for a member or element that contains JCL. While editing an element or member, enter JCLCOMMT on the Command line.
90
+
The edit macro __JCLCOMMT__ can help insert comments for a member or element that contains JCL. While editing an element or member, enter **JCLCOMMT** on the Command line.
91
+
92
+
Find JCLCOMMT.rex here - [ISPF-tools-for-Quick-Edit-and-Endevor](https://github.com/BroadcomMFD/broadcom-product-scripts/blob/Package-Shipping-Model-and-Script-Examples-update/endevor/Field-Developed-Programs/ISPF-tools-for-Quick-Edit-and-Endevor/JCLCOMMT.rex
93
+
)
94
+
95
+
## Member Inclusions
96
+
97
+
Members in the CSIQSENU library(s) use the standard ISPF Skeleton method - )IM name - for including other skeleton members.
98
+
99
+
Members of the CSIQOPTN library(s) and remote JCL PROCs and snippets may also include other members.
100
+
101
+
### For members of the CSIQOPTN library(s):
102
+
103
+
Within a member of a CSIQOPTN library, you can include other members, using this syntax.
104
+
105
+
@INCLUDE=member_name - Required Inclusion of Specific Member
106
+
@INCLUDE=(member-name) - Optional Inclusion of Specific Member
107
+
108
+
Inclusion can also be based on the presence of a member in a 3 tiered hierarchy of members. The hierarchy consists of a destination specific member, a transmission method specific member, and a non-specific member. The member names consist of a root and a one character suffix (alphabetic or national character).
109
+
110
+
Destination Specific Members: ddddddd.suffix where "ddddddd" is a Destination
111
+
Transmission Method Specific: #PSxxxx.suffix where "xxxx" is a transmission method mnemonic
112
+
Non-Specific Members: #PSNDVR.suffix
113
+
114
+
If a certain destination requires special processing, a destination specific member(s) can be created which will generate control statements for that destination only.
115
+
116
+
@INCLUDE=suffix Required Inclusion of Hierarchical Member
117
+
@INCLUDE=(suffix) Optional Inclusion of Hierarchical Member
118
+
119
+
### PROC and JCL inclusions
120
+
121
+
It might be useful to consider using a JES include, where an included member name includes the destination name, and the member itself resides in a library at the Destination site. The member may reside in a PROC library, or a library named by your JCLLIB ORDER statement. For Example:
// INCLUDE MEMBER=#&DESTID JES include from MY.REMOTE.JCL
128
+
129
+
80
130
81
131
## Tips and Techniques
82
132
83
133
Miscellaneous tips and techniques for package shipping are given here.
84
134
85
135
86
-
### Preparing a library for your Shipping software members
136
+
### Preparing an Override library for your Shipping software members
87
137
88
-
By default, Endevor builds package shipping JCL from members of the CSIQOPTN and CSIQSENU libraries. You do not need to place your modified objects into these libraries. Instead, you can create one or more "Override" libraries, and place your modified members into them. Ideally, these libraries are Endevor output libraries. **C1BMXJOB.skl** is the member that names your Override libraries. See the topic on the Override library in [Package Shipping Demystified](https://community.broadcom.com/blogs/joseph-walther/2023/11/27/package-shipping-and-post-ship-scripts-de-mystifie
89
-
). The**C1BMXJOB.skl**member in this folder gives an example, naming three "override" libraries. Any one of which may contain your modified objects.
138
+
By default, Endevor builds package shipping JCL from members of the CSIQOPTN and CSIQSENU libraries. You do not need to place your modified objects into these libraries. Instead, you can create one or more "Override" libraries, and place your modified members into them. Ideally, these libraries are managed in your admin area of Endevor. Within **C1BMXJOB.skl**, name your Override libraries. See the topic on the Override library in [Package Shipping Demystified](https://community.broadcom.com/blogs/joseph-walther/2023/11/27/package-shipping-and-post-ship-scripts-de-mystifie
139
+
). Member**C1BMXJOB.skl** gives an example by naming three "override" libraries. Any one of which may contain your modified objects.
90
140
91
141
DBOX.OVER1.ENDEVOR.ISPS
92
142
DBOX.OVER2.ENDEVOR.ISPS
93
143
DBOX.PROD.ISPS
94
144
95
-
It is not necessary to separate CSIQOPTN members from CSIQSENU members. You can choose to place override members into one library, regardless of their original locations. However, it is strongly recommended, that you comment them generously with their names in the comments.
96
145
97
146
### Using your Transmission tool for the Confirmation job
98
147
99
-
The last package shipping job is the "Notification" job. It returns back to the host the overall status of a single package shipment. See the **C1BMXRCN** reference in the [Shipment Tracking and Confirmation](https://techdocs.broadcom.com/us/en/ca-mainframe-software/devops/ca-endevor-software-change-manager/19-0/administrating/package-administration/package-ship-facility/build-track-and-confirm-package-shipments/shipment-tracking-and-confirmation.html) documentation. Package Shipping assumes an IEBGENER can write the Notification JCL to the internal reader to submit the job on the Host system. In many cases a "ROUTE XEQ" statement on the jobcard can route the job submission onto the host system. However, at some sites it is necessary to replace the IEBGENER with a file transmission to submit the Notification job. You can leverage captured variables and submit the Notification job onto the host system, using this IBM FTP example:
148
+
The last package shipping job is the "Notification" job. It returns back to the host the overall status of a single package shipment. See the **C1BMXRCN** reference in the [Shipment Tracking and Confirmation](https://techdocs.broadcom.com/us/en/ca-mainframe-software/devops/ca-endevor-software-change-manager/19-0/administrating/package-administration/package-ship-facility/build-track-and-confirm-package-shipments/shipment-tracking-and-confirmation.html) documentation. Package Shipping assumes an IEBGENER can write the Notification JCL to the internal reader to submit the job on the Host system. In many cases a "ROUTE XEQ" statement on the jobcard is all that is necessary. However at some sites, the IEBGENER must be replaced with a file transmission step to submit the Notification job. You can submit the Notification job onto the host system, using this IBM FTP example:
100
149
101
150
102
151
Here is an example of using IBM's FTP within the C1BMXRCN skeleton member.
@@ -133,19 +182,18 @@ Here is an example of using IBM's FTP within the C1BMXRCN skeleton member.
Notice that the &RMOTHLQ, &DATE6 and &TIME6 variables are among those captured by the TAILOR step within C1BMXIN.
185
+
Notice that the &RMOTHLQ, &DATE6 and &TIME6 variables are among those captured or created by the TAILOR step within C1BMXIN.
137
186
138
187
### IEBPTPCH
139
188
140
-
IEBPTPCH is an IBM utility program that is used to print or punch records from a sequential or partitioned dataset. The utility can perform various tasks, including copying members from a partitioned dataset (PDS) into a sequential dataset (PS). If you have shipped members of a datset that contain commands, such as DB2 Binds or CICS newcopies, then IEBPTPCH is useful for writing all the shipped members into a sequential file for subsequent processing.
141
-
189
+
IEBPTPCH is an IBM utility program that is used to print or punch records from a sequential or partitioned dataset. Our examples show using IEBPTPCH to write all members of a "Staging" dataset into a single output file. It is useful for shipped objects such as DB2 Binds or CICS newcopies. Then, the output is further processed in subsequent steps in the shipping job.
142
190
See the __#RJNDVRA__ member example.
143
191
144
192
### Multiple Endevors
145
193
146
-
If you are running multiple Endevors, it would be unreasonable to expect that dataset names and jobcard values (for example) be the same on all of them. A more reasonable expectation is to allow each Endevor (or Lpar) to use its own dataset names, jobcard values and other site-specific variations.
194
+
If you are running multiple Endevors, it would be unreasonable to expect that dataset names and jobcard values (for example) be the same on all of them. A more realistic expectation is for each Endevor (or Lpar) to use its own dataset names, jobcard values and other image-specific variations.
147
195
148
-
If **DBOX** is the name of an Lpar, then **@DBOX** is the name of a "callable Rexx" service, providing site-specific information for just that Lpar. Other Lpars can have their own "callable Rexx" services too. Then, the necessary differences from one Endevor to the next can be managed in "callable Rexx" service routines, and not managed in the common code. The example **C1BMXIN.skl**, paired with the **@DBOX** member, shows how this can be done.
196
+
If **DBOX** is the name of an Lpar, then **@DBOX** is the name of a "callable Rexx" service, providing image-specific information for just that Lpar. Other Lpars can have their own "callable Rexx" services too. Then, the necessary differences from one Endevor to the next can be managed in "callable Rexx" service routines, and not managed in the common code. The example **C1BMXIN.skl**, paired with the **@DBOX** member, shows how this is done.
149
197
150
198
A "callable Rexx" service can be engaged anywhere REXX is run. One of the places is within an ISPF skeleton. Member **C1BMXIN.skl** references a CSIQCLS0 library whose name might differ from one Lpar to the next. When running on the DBOX Lpar, it calls **@DBOX** for the value of **MyCLS0Library** and assigns the returned dataset name to a new variable named **CSIQCLS0**. Then, the **&CSIQCLS0** variable will be replaced with the datset name whenever it is found.
151
199
@@ -193,11 +241,4 @@ Lines 13 and 14 show the REXX code identifying where it is running. The **MVSVAR
193
241
194
242
Engaging a "callable REXX" service may also be performed from other REXX programs, such as an Endevor REXX exit or from REXX zowe executions.
195
243
196
-
One final note about about the CSIQCLS0 variable. The variable is created brand new in the REXX portion of the C1BMXIN skeleton, and is used as an ISPF variable later on the TAILOR step. You can make variables like CSIQCLS0 be both an ISPF variable and a Table Tool variable, if it is included in the OPTIONS of the TAILOR step.
One final note about the CSIQCLS0 variable. The variable is created brand new in the REXX portion of the C1BMXIN skeleton, and is used as an ISPF variable later on the TAILOR step. You can make variables like CSIQCLS0 be both an ISPF variable and a Table Tool variable, if it is included in the OPTIONS of the TAILOR step.
0 commit comments