Module JobSubmissionService
Macros to execute jobs and to report the status of a submitted job.
Since: 2.1
Macro Summary |
external
LSAF | %lsaf_getjobmanifestinfo(lsaf_path=, lsaf_version=, sas_dsname=work.lsafGetJobManifestInfo);
Gets the information for a job manifest in the repository. The information is stored in a SAS ...
|
external
LSAF | %lsaf_getjobmanifestinputs(lsaf_path=, lsaf_version=, sas_dsname=work.lsafGetJobManifestInputs);
Gets the metadata for the input files for the specified job manifest in the repository. The ...
|
external
LSAF | %lsaf_getjobmanifestmetrics(lsaf_path=, lsaf_version=, sas_dsname=work.lsafgetjobmanifestmetrics);
Gets the metrics for the specified job manifest in the repository. The data is stored in a ...
|
external
LSAF | %lsaf_getjobmanifestoutputs(lsaf_path=, lsaf_version=, sas_dsname=work.lsafGetJobManifestOutputs);
Gets the metadata for the output files for the specified job manifest in the repository. The ...
|
external
LSAF | %lsaf_getjobmanifestparameters(lsaf_path=, lsaf_version=, sas_dsname=work.lsafGetJobManifestParameters);
Gets the metadata for the parameters for the specified job manifest in the repository. The ...
|
external
LSAF | %lsaf_getjobmanifestprograms(lsaf_path=, lsaf_version=, sas_dsname=work.lsafGetJobManifestPrograms);
Gets the metadata for the programs for the specified job manifest in the repository. The ...
|
external
LSAF | %lsaf_getjobpublishhistory(lsaf_path=, sas_dsname=work.lsafGetJobPublishHistory);
Gets the publish history for the specified job in the repository. The metadata is stored in a ...
|
external
LSAF | %lsaf_getsubmissionstatus(lsaf_jobsubmission_id=);
Gets the status of a repository or workspace job submission.
|
external
LSAF | %lsaf_submitandpopulatewsjob(lsaf_path=, lsaf_userelativepaths=0, sas_dsname=);
Submits a workspace job for immediate execution, and updates the input and output specifications ...
|
external
LSAF | %lsaf_submitjob(lsaf_path=, lsaf_version=, sas_dsname=);
Submits a repository job for immediate execution and sets the SAS macro variable ...
|
external
LSAF | %lsaf_submitworkspacejob(lsaf_path=, sas_dsname=);
Submits a workspace job for immediate execution, and sets the SAS macro variable ...
|
%lsaf_getjobmanifestinfo(lsaf_path=, lsaf_version=, sas_dsname=work.lsafGetJobManifestInfo);
[ Exposure:
external
]
- Gets the information for a job manifest in the repository. The information is stored in a SAS
data set. The output data set can be used as an input data set for the lsaf_createworkspacejob
macro.
This is the information that is displayed on the Details tab of the job manifest and the
information that concerns the versioning of new output files.
Syntax:
%LSAF_GETJOBMANIFESTINFO(LSAF_PATH=lsaf-path <, LSAF_VERSION=lsaf-version,
SAS_DSNAME=SAS-data-set>);
-
History:
- 2019-12-03
- initial coding.
-
-
Expected Macro Variables:
-
_lsafMsg_
-
The return message.
-
_lsafRC_
-
The return code.
-
Parameters:
-
lsaf_path
-
- Required - The case-sensitive path of the job manifest.
-
lsaf_version
-
- Optional - The specific version number of the job manifest. If not
specified, the information for the latest version is returned. Specifying a version
for a non-versioned job manifest causes an error.
-
sas_dsname
-
- Optional - The name of the output SAS data set that contains the metadata
for the manifest, specified as libref.dataset. The default value is
WORK.LSAFGETJOBMANIFESTINFO. The data set contains variables that represent each
element of the metadata for the job manifest. The data set is sorted by the NAME
variable. The following metadata is represented in the data set.
- path: The path of the job manifest.
- version: The version number that is associated with the job manifest.
- name: The name of the property or attribute.
- value: The value of the property or attribute.
-
File: lsaf_getjobmanifestinfo.sas
-
First available in version: 2.3
%lsaf_getjobmanifestinputs(lsaf_path=, lsaf_version=, sas_dsname=work.lsafGetJobManifestInputs);
[ Exposure:
external
]
- Gets the metadata for the input files for the specified job manifest in the repository. The
metadata is stored in a SAS data set.
Syntax:
%LSAF_GETJOBMANIFESTINPUTS(LSAF_PATH=lsaf-path <LSAF_VERSION=lsaf-version,
SAS_DSNAME=SAS-data-set>);
-
History:
- 2019-11-01
- initial coding.
-
-
Expected Macro Variables:
-
_lsafMsg_
-
The return message.
-
_lsafRC_
-
The return code.
-
Parameters:
-
lsaf_path
-
- Required - The case-sensitive path of the job manifest.
-
lsaf_version
-
- Optional - The version of the job manifest. If not specified, the latest
version is used.
-
sas_dsname
-
- Optional - The name of the output SAS data set to contain the metadata
for the inputs, specified as libref.dataset. The default value is
WORK.LSAFGETJOBMANIFESTINPUTS. The data set contains a row for each job manifest
input and columns with the following names. The data set retains the order of the
inputs.
- jobManifestPath: The path of the job manifest.
- jobManifestVersion: The job manifest version.
- jobLocation: The job source location.
- path: The path of the input file.
- version: The version of the input file that is used in the job submission, or
blank, if the file is not versioned.
- size: The size (in bytes) of the input file.
- sizeFormatted: The formatted size (in bytes, KB, MB, or TB) of the input file.
- referenceProgram: The referenced SAS program file.
-
File: lsaf_getjobmanifestinputs.sas
-
First available in version: 2.3
%lsaf_getjobmanifestmetrics(lsaf_path=, lsaf_version=, sas_dsname=work.lsafgetjobmanifestmetrics);
[ Exposure:
external
]
- Gets the metrics for the specified job manifest in the repository. The data is stored in a
SAS data set.
Syntax:
%LSAF_GETJOBMANIFESTMETRICSS(LSAF_PATH=lsaf-path <,LSAF_VERSION=lsaf-version,
SAS_DSNAME=SAS-data-set>);
-
History:
- 2019-11-08
- initial coding.
-
-
Expected Macro Variables:
-
_lsafMsg_
-
The return message.
-
_lsafRC_
-
The return code.
-
Parameters:
-
lsaf_path
-
- Required - The path of the job manifest.
-
lsaf_version
-
- Optional - The version of the job manifest. If not specified, the latest
version is used.
-
sas_dsname
-
- Optional - The name of the output SAS data set to contain the manifest
metrics, specified as libref.dataset. The default value is
WORK.LSAFGETJOBMANIFESTMETRICS. The data set contains a row for each job manifest
type and columns with the following names. The data set retains the order of the
manifest types.
- jobManifestPath: The path of the job manifest.
- jobManifestVersion: The job manifest version.
- type: The type of metric.
- total: The total for the metric.
- size: The size of the metric.
- formattedsize: The formatted size (in bytes, KB, MB, or TB).
- time: The time or interval of the metric.
- formattedtime: The formatted time or interval of the metric, which is displayed
as h:m:s:ms.
-
File: lsaf_getjobmanifestmetrics.sas
-
First available in version: 2.3
%lsaf_getjobmanifestoutputs(lsaf_path=, lsaf_version=, sas_dsname=work.lsafGetJobManifestOutputs);
[ Exposure:
external
]
- Gets the metadata for the output files for the specified job manifest in the repository. The
metadata is stored in a SAS data set.
Syntax:
%LSAF_GETJOBMANIFESTOUTPUTS(LSAF_PATH=lsaf-path <LSAF_VERSION=lsaf-version,
SAS_DSNAME=SAS-data-set>);
-
History:
- 2019-11-01
- initial coding.
-
-
Expected Macro Variables:
-
_lsafMsg_
-
The return message.
-
_lsafRC_
-
The return code.
-
Parameters:
-
lsaf_path
-
- Required - The case-sensitive path of the job manifest.
-
lsaf_version
-
- Optional - The version of the job manifest. If not specified, the latest
version is used.
-
sas_dsname
-
- Optional - The name of the output SAS data set to contain the metadata
for the outputs, specified as libref.dataset. The default value is
WORK.LSAFGETJOBMANIFESTOUTPUTS. The data set contains a row for each job manifest
output and columns with the following names. The data set retains the order of the
inputs.
- jobManifestPath: The path of the job manifest.
- jobManifestVersion: The job manifest version.
- jobLocation: The job source location.
- path: The path of the output file.
- version: The version of the output file that is used in the job submission, or
blank, if the output file is not versioned.
- size: The size (in bytes) of the output file.
- sizeFormatted: The formatted size (in bytes, KB, MB, or TB) of the output file.
- referenceProgram: The referenced SAS program file.
-
File: lsaf_getjobmanifestoutputs.sas
-
First available in version: 2.3
%lsaf_getjobmanifestparameters(lsaf_path=, lsaf_version=, sas_dsname=work.lsafGetJobManifestParameters);
[ Exposure:
external
]
- Gets the metadata for the parameters for the specified job manifest in the repository. The
metadata is stored in a SAS data set.
Syntax:
%LSAF_GETJOBMANIFESTPARAMETERS(LSAF_PATH=lsaf-path <,LSAF_VERSION=lsaf-version,
SAS_DSNAME=SAS-data-set>);
-
History:
- 2019-11-13
- initial coding.
-
-
Expected Macro Variables:
-
_lsafMsg_
-
The return message.
-
_lsafRC_
-
The return code.
-
Parameters:
-
lsaf_path
-
- Required - The case-sensitive path of the job manifest.
-
lsaf_version
-
- Optional - The version of the job manifest. If not specified, the latest
version is used.
-
sas_dsname
-
- Optional - The name of the output SAS data set to contain the metadata
for the parameters, specified as libref.dataset. The default value is
WORK.LSAFGETJOBMANIFESTPARAMETERS. The data set contains a row for each job manifest
parameter and columns with the following names.
- jobManifestPath: The path of the job manifest.
- jobManifestVersion: The job manifest version.
- jobLocation: The job source location.
- name: The label of the parameter.
- type: The type of the parameter.
- label: The label of the parameter.
- value: The value of the parameter.
- version: The version of the file that is used in the job submission, or blank, if
file is not versioned.
- includeSubfolders: Indicates whether to include subfolders. Valid values: 0: No,
1: Yes.
-
File: lsaf_getjobmanifestparameters.sas
-
First available in version: 2.3
%lsaf_getjobmanifestprograms(lsaf_path=, lsaf_version=, sas_dsname=work.lsafGetJobManifestPrograms);
[ Exposure:
external
]
- Gets the metadata for the programs for the specified job manifest in the repository. The
metadata is stored in a SAS data set.
Syntax:
%LSAF_GETJOBMANIFESTPROGRAMS(LSAF_PATH=lsaf-path <LSAF_VERSION=lsaf-version,
SAS_DSNAME=SAS-data-set>);
-
History:
- 2019-11-01
- initial coding.
-
-
Expected Macro Variables:
-
_lsafMsg_
-
The return message.
-
_lsafRC_
-
The return code.
-
Parameters:
-
lsaf_path
-
- Required - The case-sensitive path of the job manifest.
-
lsaf_version
-
- Optional - The version of the job manifest. If not specified, the latest
version is used.
-
sas_dsname
-
- Optional - The name of the output SAS data set to contain the metadata
for the programs, specified as libref.dataset. The default value is
WORK.LSAFGETJOBMANIFESTPROGRAMS. The data set contains a row for each job manifest
program and columns with the following names. The data set retains the order of the
programs.
- jobManifestPath: The path of the job manifest.
- jobManifestVersion: The job manifest version.
- jobLocation: The job source location.
- path: The path of the program file.
- version: The version of the program file that is used in the job submission, or
blank if, program file is not versioned.
- size: The size (in bytes) of the program.
- sizeFormatted: The formatted size (in bytes, KB, MB, or TB) of the input file.
-
File: lsaf_getjobmanifestprograms.sas
-
First available in version: 2.3
%lsaf_getjobpublishhistory(lsaf_path=, sas_dsname=work.lsafGetJobPublishHistory);
[ Exposure:
external
]
- Gets the publish history for the specified job in the repository. The metadata is stored in a
SAS data set.
Syntax:
%LSAF_GETJOBPUBLISHHISTORY(LSAF_PATH=lsaf-path <,SAS_DSNAME=SAS-data-set>);
-
History:
- 2019-11-13
- initial coding.
-
-
Expected Macro Variables:
-
_lsafMsg_
-
The return message.
-
_lsafRC_
-
The return code.
-
Parameters:
-
lsaf_path
-
- Required - The case-sensitive path of the job file.
-
sas_dsname
-
- Optional - The name of the output SAS data set to contain the metadata
for the publish history, specified as libref.dataset. The default value is
WORK.LSAFGETJOBPUBLISHHISTORY. The data set contains a row for each job publish
history and columns with the following names.
- path: The path of the job file.
- id: The identifier of the job file.
- version: The version of the job file that is associated with the submission.
- sessionId: The session identifier of the job submission.
- submittedBy: The identifier of the user who submitted the job.
- submittedDate: The date on which the job was submitted.
- submittedDateSAS: The SAS-formatted date on which the job was submitted,
in DATETIME format.
- completedDate: The date on which the submitted job was completed.
- completedDateSAS: The SAS-formatted date on which the submitted job was completed,
in DATETIME format.
- summaryStatus: The summary status of the job submission.
- detailStatus: The detail status of the job submission.
- runAsUser: The identifier of the run-as user account that is associated with
running the job.
-
File: lsaf_getjobpublishhistory.sas
-
First available in version: 2.3
%lsaf_getsubmissionstatus(lsaf_jobsubmission_id=);
[ Exposure:
external
]
- Gets the status of a repository or workspace job submission.
The SAS macro variable _lsafJobSubmissionStatus_ is set to the status value. The values are
NOT_SET, NOT_STARTED, STARTED, RUNNING_TASKS, POST_EXECUTION_PUBLISHING, COMPLETED_SUCCESSFUL,
COMPLETED_SASERRORS, COMPLETED_CHECKIN_ERROR, COMPLETED_SASERRORS_CHECKIN_ERROR,
COMPLETED_FAILED, COMPLETED_CANCELED, COMPLETED_SASWARNINGS, and
COMPLETED_SASWARNINGS_CHECKIN_ERROR.
If the macro runs without error, _lsafRC_ is set to 0, the _lsafJobSubmissionStatus_
macro variable is set to the appropriate value, and a job submission status message is
printed to the SAS log file. If the job completed with warnings or errors, the job submission
message shows in the SAS log file as a warning or an error, as appropriate.
Syntax:
%LSAF_GETSUBMISSIONSTATUS(LSAF_JOBSUBMISSION_ID=job-submission-id)
-
History:
- 2014-04-07
- initial code
- 2016-08-26
- rebrand as LSAF
- 2016-11-02
- added job submission message, updated doc
- 2019-02-11
- update to 2.1
- 2020-03-02
- DE14415 fix
-
-
Expected Macro Variables:
-
_lsafJobSubmissionStatus_
-
The job submission status.
-
_lsafMsg_
-
The return message.
-
_lsafRC_
-
The return code.
-
Parameters:
-
lsaf_jobsubmission_id
-
- Required - The submission identifier returned from the
lsaf_submitjob macro.
-
File: lsaf_getsubmissionstatus.sas
-
First available in version: 1.4
%lsaf_submitandpopulatewsjob(lsaf_path=, lsaf_userelativepaths=0, sas_dsname=);
[ Exposure:
external
]
- Submits a workspace job for immediate execution, and updates the input and output specifications
in the job based on inputs and outputs that are accessed during the job run. The SAS macro
variable _lsafPopulateWsJobSummissionId_ is set to the identifier for the job submission. If the
job cannot be submitted, _lsafPopulateWsJobSummissionId_ is set to blank.
If the job runs with errors, the job is not updated. If the job runs successfully or with
warnings, it is updated, and it replaces any existing input and output definitions in the job.
A data set that represents the job parameters values to overwrite for the current job submission
can be specified in the call of lsaf_submitandpopulatewsjob. If no job parameters data set is
specified, the default values for all job parameters are used.
The output data sets from either lsaf_getjobparameters or lsaf_getworkspacejobparameters
contain all of the data that is relevant to the parameters for a specific job and can be used as
a source for the input parameters data set for the lsaf_submitandpopulatewsjob macro. Modify the
data set with changes prior to calling lsaf_submitandpopulatewsjob.
- Rename the defaultValue variable to "value" or add a variable with the name "value" to
indicate the values to use for the current submission.
- Default job parameter values are used for missing parameters (deleted rows).
- Specifying an empty string for a parameter value results in using a blank as the parameter
value for the current submission.
- Added parameters are ignored.
- The parameters in the input data set are matched with the job parameters by name and type.
If no match is found for a parameter, its default value is used.
- Data set rows with duplicate values for a parameter name cause an execution error.
- DATE job parameter values must be in SAS datetime18. format (such as 02NOV2013:09:33:22) or
in SAS E8601DZ25. format (such as 2013-11-02T09:33:22-04:00). For SAS datetime18. format, an
offset of zero hours from GMT is used. To specify an offset from GMT, use the E8601DZ25. format.
Date values in formats other than the two described above result in an execution error.
Syntax:
%LSAF_SUBMITANDPOPULATEWSJOB(LSAF_PATH=lsaf-path <, LSAF_USERELATIVEPATHS=use-relative-paths,
SAS_DSNAME=SAS-data-set>);
-
History:
- 2016-10-20
- initial coding
- 2019-02-11
- update to 2.1
-
-
Expected Macro Variables:
-
_lsafMsg_
-
The return message.
-
_lsafPopulateWsJobSummissionId_
-
The job submission identifier.
-
_lsafRC_
-
The return code.
-
Parameters:
-
lsaf_path
-
- Required - The path of the job in the workspace of the current user.
-
lsaf_userelativepaths
-
- Optional - Indicates whether to generate inputs and outputs
as absolute or relative paths. Valid values:
- 0 (Default): Absolute paths.
- 1: Relative paths.
-
sas_dsname
-
- Optional - The name of the SAS data set that contains the job parameter
information, specified as libref.dataset. If not specified, the default job
parameters values aree used. The data set must contain at least the character
variables listed below. Additional variables are ignored.
- name: The name of the parameter.
- type: The parameter type. Valid values: CHARACTER, CHARACTER_MASKED, NUMERIC,
DATE, FILE, and FOLDER.
- value: The value of the parameter to use in the current job submission.
- fileVersion: The file version to use, if the parameter is of type FILE.
For versioned files, a blank value specifies the latest file version used. For
unversioned files, the value is ignored.
- includeSubFolders: Indicates whether the subfolders of a container are included
during job execution.
-
File: lsaf_submitandpopulatewsjob.sas
-
First available in version: 1.5
%lsaf_submitjob(lsaf_path=, lsaf_version=, sas_dsname=);
[ Exposure:
external
]
- Submits a repository job for immediate execution and sets the SAS macro variable
_lsafJobSubmissionId_ to the identifier for the job submission. If the job cannot be submitted,
_lsafJobSubmissionId_ is set to blank.
A data set that represents the job parameters values to overwrite for the currentjob submission
can be specified in the call of lsaf_submitjob. If no job parameters data set is specified, the
default values for all job parameters are used.
The output data set from the macro lsaf_getjobparameters contains all of the data that is relevant
to the parameters for a specific job and can be used as a source for the input parameters data
set for the lsaf_submitjob macro. Modify the data set with any changes prior to calling
lsaf_submitjob.
- Rename the defaultValue variable to "value" or add a variable with the name "value" to
indicate the values to use for the current submission.
- Default job parameter values are used for missing parameters (deleted rows).
- Indicating an empty string for a parameter value results in using a blank as the parameter
value for the current submission.
- Added parameters are ignored.
- The parameters in the input data set are matched with the job parameters by name and type.
If no match is found for a parameter, its default value is used.
- Data set rows with duplicate values for parameter name cause an execution error.
- DATE job parameter values must be in SAS datetime18. format (such as 02NOV2013:09:33:22), or
in SAS E8601DZ25. format (such as 2013-11-02T09:33:22-04:00). For SAS datetime18. format, an
offset of zero hours from GMT is used. To specify an offset from GMT, use the E8601DZ25.
format. Date values in formats other than the two described above result in an execution error.
Syntax:
%LSAF_SUBMITJOB(LSAF_PATH=lsaf-path <, LSAF_VERSION=lsaf-version,
SAS_DSNAME=SAS-data-set>);
-
History:
- 2014-04-09
- initial coding
- 2016-08-26
- rebrand as LSAF
- 2019-02-11
- update to 2.1
-
-
Expected Macro Variables:
-
_lsafJobSubmissionId_
-
The job submission identifier.
-
_lsafMsg_
-
The return message.
-
_lsafRC_
-
The return code.
-
Parameters:
-
lsaf_path
-
- Required - The path of the job in the repository.
-
lsaf_version
-
- Optional - The specific version number of the job. If not specified, the
the latest version of the job is submitted. Specifying a version for a non-versioned
file causes an error.
-
sas_dsname
-
- Optional - The name of the SAS data set that contains the job parameter
information, specified as libref.dataset. If not specified, the default job parameters
values are used. The data set must contain at least the character variables that are
listed below. Additional variables are ignored.
- name: The name of the parameter.
- type: The parameter type. Valid values: CHARACTER, CHARACTER_MASKED, NUMERIC,
DATE, FILE, and FOLDER.
- value: The value of the parameter to use in the current job submission.
- fileVersion: The file version to use, if the parameter is of type FILE. For
versioned files, a blank value results in the latest file version used. For
unversioned files, the value is ignored.
- includeSubFolders: Indicates whether the subfolders of a container are included
during job execution.
-
File: lsaf_submitjob.sas
-
First available in version: 1.4
%lsaf_submitworkspacejob(lsaf_path=, sas_dsname=);
[ Exposure:
external
]
- Submits a workspace job for immediate execution, and sets the SAS macro variable
_lsafWorkspaceJobSubmissionId_ to the identifier for the job submission. If the job cannot be
submitted, _lsafWorkspaceJobSubmissionId_ is set to blank.
A data set that represents the job parameter values to overwrite for the current job submission
can be specified in the call to lsaf_submitworkspacejob. If no job parameters data set is
specified, the default values for all job parameters are used.
The output data sets from either lsaf_getjobparameters or lsaf_getworkspacejobparameters contain
all of the data that is relevant to the parameters for a specific job and can be used as a source
for the input parameters data set for the lsaf_submitworkspacejob macro. Modify the data set with
any changes prior to calling lsaf_submitworkspacejob.
- Rename the defaultValue variable to "value" or add a variable with the name "value" to
indicate the values to use for the current submission.
- Default job parameter values are used for missing parameters (deleted rows).
- Specifying an empty string for a parameter value results in using a blank as the parameter
value for the current submission.
- Added parameters are ignored.
- The parameters in the input data set are matched with the job parameters by name and type.
If no match is found for a parameter, its default value is used.
- Data set rows with duplicate values for parameter name cause an execution error.
- DATE job parameter values must be in SAS datetime18. format (such as 02NOV2013:09:33:22), or
in SAS E8601DZ25. format (such as 2013-11-02T09:33:22-04:00). For SAS datetime18. format, an
offset of zero hours from GMT is used. To specify an offset from GMT, use the E8601DZ25.
format. Date values in formats other than the two described above result in an execution error.
Syntax:
%LSAF_SUBMITWORKSPACEJOB(LSAF_PATH=lsaf-path <, SAS_DSNAME=SAS-data-set>);
-
History:
- 2016-10-20
- initial coding
- 2019-02-11
- update to 2.1
-
-
Expected Macro Variables:
-
_lsafMsg_
-
The return message.
-
_lsafRC_
-
The return code.
-
_lsafWorkspaceJobSubmissionId_
-
The job submission identifier.
-
Parameters:
-
lsaf_path
-
- Required - The path of the job in the workspace of the current user.
-
sas_dsname
-
- Optional - The name of the SAS data set that contains the job parameter
information, specified as libref.dataset. If not specified, the default job
parameters values are used. The data set must contain at least the characater
variables that are listed below. Additional variables are ignored.
- name: The name of the parameter.
- type: The parameter type. Valid values: CHARACTER, CHARACTER_MASKED, NUMERIC,
DATE, FILE, and FOLDER.
- value: The value of the parameter to use in the current job submission.
- fileVersion: The file version to use, if the parameter is of type FILE.
For versioned files, a blank value results in the latest file version used.
For unversioned files, the value is ignored.
- includeSubFolders: Indicates whether the subfolders of a container are included
during job execution.
-
File: lsaf_submitworkspacejob.sas
-
First available in version: 1.5