logo

oasis-root

Compiled tree of Oasis Linux based on own branch at <https://hacktivis.me/git/oasis/> git clone https://anongit.hacktivis.me/git/oasis-root.git

qalter.1p (28053B)


  1. '\" et
  2. .TH QALTER "1P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
  3. .\"
  4. .SH PROLOG
  5. This manual page is part of the POSIX Programmer's Manual.
  6. The Linux implementation of this interface may differ (consult
  7. the corresponding Linux manual page for details of Linux behavior),
  8. or the interface may not be implemented on Linux.
  9. .\"
  10. .SH NAME
  11. qalter
  12. \(em alter batch job
  13. .SH SYNOPSIS
  14. .LP
  15. .nf
  16. qalter \fB[\fR-a \fIdate_time\fB] [\fR-A \fIaccount_string\fB] [\fR-c \fIinterval\fB] [\fR-e \fIpath_name\fB]
  17. [\fR-h \fIhold_list\fB] [\fR-j \fIjoin_list\fB] [\fR-k \fIkeep_list\fB] [\fR-l \fIresource_list\fB]
  18. [\fR-m \fImail_options\fB] [\fR-M \fImail_list\fB] [\fR-N \fIname\fB] [\fR-o \fIpath_name\fB]
  19. [\fR-p \fIpriority\fB] [\fR-r \fIy\fR|\fIn\fB] [\fR-S \fIpath_name_list\fB] [\fR-u \fIuser_list\fB]
  20. \fIjob_identifier\fR...
  21. .fi
  22. .SH DESCRIPTION
  23. The attributes of a batch job are altered by a request to the batch
  24. server that manages the batch job. The
  25. .IR qalter
  26. utility is a user-accessible batch client that requests the alteration
  27. of the attributes of one or more batch jobs.
  28. .P
  29. The
  30. .IR qalter
  31. utility shall alter the attributes of those batch jobs, and only those
  32. batch jobs, for which a batch
  33. .IR job_identifier
  34. is presented to the utility.
  35. .P
  36. The
  37. .IR qalter
  38. utility shall alter the attributes of batch jobs in the order in which
  39. the batch
  40. .IR job_identifier s
  41. are presented to the utility.
  42. .P
  43. If the
  44. .IR qalter
  45. utility fails to process a batch
  46. .IR job_identifier
  47. successfully, the utility shall proceed to process the remaining batch
  48. .IR job_identifier s,
  49. if any.
  50. .P
  51. For each batch
  52. .IR job_identifier
  53. for which the
  54. .IR qalter
  55. utility succeeds, each attribute of the identified batch job shall be
  56. altered as indicated by all the options presented to the utility.
  57. .P
  58. For each identified batch job for which the
  59. .IR qalter
  60. utility fails, the utility shall not alter any attribute of the batch
  61. job.
  62. .P
  63. For each batch job that the
  64. .IR qalter
  65. utility processes, the utility shall not modify any attribute other
  66. than those required by the options and option-arguments presented to
  67. the utility.
  68. .P
  69. The
  70. .IR qalter
  71. utility shall alter batch jobs by sending a
  72. .IR "Modify Job Request"
  73. to the batch server that manages each batch job. At the time the
  74. .IR qalter
  75. utility exits, it shall have modified the batch job corresponding to
  76. each successfully processed batch
  77. .IR job_identifier .
  78. An attempt to alter the attributes of a batch job in the RUNNING state
  79. is implementation-defined.
  80. .SH OPTIONS
  81. The
  82. .IR qalter
  83. utility shall conform to the Base Definitions volume of POSIX.1\(hy2017,
  84. .IR "Section 12.2" ", " "Utility Syntax Guidelines".
  85. .P
  86. The following options shall be supported by the implementation:
  87. .IP "\fB\-a\ \fIdate_time\fR" 10
  88. Redefine the time at which the batch job becomes eligible for
  89. execution.
  90. .RS 10
  91. .P
  92. The
  93. .IR date_time
  94. argument shall be in the same form and represent the same time as for
  95. the
  96. .IR touch
  97. utility. The time so represented shall be set into the
  98. .IR Execution_Time
  99. attribute of the batch job. If the time specified is earlier than the
  100. current time, the
  101. .BR \-a
  102. option shall have no effect.
  103. .RE
  104. .IP "\fB\-A\ \fIaccount_string\fR" 10
  105. .br
  106. Redefine the account to which the resource consumption of the batch job
  107. should be charged.
  108. .RS 10
  109. .P
  110. The syntax of the
  111. .IR account_string
  112. option-argument is unspecified.
  113. .P
  114. The
  115. .IR qalter
  116. utility shall set the
  117. .IR Account_Name
  118. attribute of the batch job to the value of the
  119. .IR account_string
  120. option-argument.
  121. .RE
  122. .IP "\fB\-c\ \fIinterval\fR" 10
  123. Redefine whether the batch job should be checkpointed, and if so, how
  124. often.
  125. .RS 10
  126. .P
  127. The
  128. .IR qalter
  129. utility shall accept a value for the interval option-argument that is
  130. one of the following:
  131. .IP "\fRn\fP" 10
  132. No checkpointing is to be performed on the batch job
  133. (NO_CHECKPOINT).
  134. .IP "\fRs\fP" 10
  135. Checkpointing is to be performed only when the batch server is shut
  136. down (CHECKPOINT_AT_SHUTDOWN).
  137. .IP "\fRc\fP" 10
  138. Automatic periodic checkpointing is to be performed at the
  139. .IR Minimum_Cpu_Interval
  140. attribute of the batch queue, in units of CPU minutes
  141. (CHECKPOINT_AT_MIN_CPU_INTERVAL).
  142. .IP "\fRc\fR=\fIminutes\fR" 10
  143. Automatic periodic checkpointing is to be performed every
  144. .IR minutes
  145. of CPU time, or every
  146. .IR Minimum_Cpu_Interval
  147. minutes, whichever is greater. The
  148. .IR minutes
  149. argument shall conform to the syntax for unsigned integers and shall be
  150. greater than zero.
  151. .P
  152. An implementation may define other checkpoint intervals. The
  153. conformance document for an implementation shall describe any
  154. alternative checkpoint intervals, how they are specified, their
  155. internal behavior, and how they affect the behavior of the utility.
  156. .P
  157. The
  158. .IR qalter
  159. utility shall set the
  160. .IR Checkpoint
  161. attribute of the batch job to the value of the
  162. .IR interval
  163. option-argument.
  164. .RE
  165. .IP "\fB\-e\ \fIpath_name\fR" 10
  166. .br
  167. Redefine the path to be used for the standard error stream of the batch
  168. job.
  169. .RS 10
  170. .P
  171. The
  172. .IR qalter
  173. utility shall accept a
  174. .IR path_name
  175. option-argument that conforms to the syntax of the
  176. .IR path_name
  177. element defined in the System Interfaces volume of POSIX.1\(hy2017, which can be preceded by a host name
  178. element of the form
  179. .IR hostname :.
  180. .P
  181. If the
  182. .IR path_name
  183. option-argument constitutes an absolute pathname, the
  184. .IR qalter
  185. utility shall set the
  186. .IR Error_Path
  187. attribute of the batch job to the value of the
  188. .IR path_name
  189. option-argument, including the host name element, if present.
  190. .P
  191. If the
  192. .IR path_name
  193. option-argument constitutes a relative pathname and no host name
  194. element is specified, the
  195. .IR qalter
  196. utility shall set the
  197. .IR Error_Path
  198. attribute of the batch job to the value of the absolute pathname
  199. derived by expanding the
  200. .IR path_name
  201. option-argument relative to the current directory of the process that
  202. executes the
  203. .IR qalter
  204. utility.
  205. .P
  206. If the
  207. .IR path_name
  208. option-argument constitutes a relative pathname and a host name
  209. element is specified, the
  210. .IR qalter
  211. utility shall set the
  212. .IR Error_Path
  213. attribute of the batch job to the value of the option-argument without
  214. expansion.
  215. .P
  216. If the
  217. .IR path_name
  218. option-argument does not include a host name element, the
  219. .IR qalter
  220. utility shall prefix the pathname in the
  221. .IR Error_Path
  222. attribute with
  223. .IR hostname :,
  224. where
  225. .IR hostname
  226. is the name of the host upon which the
  227. .IR qalter
  228. utility is being executed.
  229. .RE
  230. .IP "\fB\-h\ \fIhold_list\fR" 10
  231. Redefine the types of holds, if any, on the batch job. The
  232. .IR qalter
  233. .BR \-h
  234. option shall accept a value for the
  235. .IR hold_list
  236. option-argument that is a string of alphanumeric characters in the
  237. portable character set.
  238. .RS 10
  239. .P
  240. The
  241. .IR qalter
  242. utility shall accept a value for the
  243. .IR hold_list
  244. option-argument that is a string of one or more of the characters
  245. .BR 'u' ,
  246. .BR 's' ,
  247. or
  248. .BR 'o' ,
  249. or the single character
  250. .BR 'n' .
  251. For each unique character in the
  252. .IR hold_list
  253. option-argument, the
  254. .IR qalter
  255. utility shall add a value to the
  256. .IR Hold_Types
  257. attribute of the batch job as follows, each representing a different
  258. hold type:
  259. .IP "\fRu\fP" 6
  260. USER
  261. .IP "\fRs\fP" 6
  262. SYSTEM
  263. .IP "\fRo\fP" 6
  264. OPERATOR
  265. .P
  266. If any of these characters are duplicated in the
  267. .IR hold_list
  268. option-argument, the duplicates shall be ignored. An existing
  269. .IR Hold_Types
  270. attribute can be cleared by the hold type:
  271. .IP "\fRn\fP" 6
  272. NO_HOLD
  273. .P
  274. The
  275. .IR qalter
  276. utility shall consider it an error if any hold type other than
  277. .BR 'n'
  278. is combined with hold type
  279. .BR 'n' .
  280. Strictly conforming applications shall not repeat any of the characters
  281. .BR 'u' ,
  282. .BR 's' ,
  283. .BR 'o' ,
  284. or
  285. .BR 'n'
  286. within the
  287. .IR hold_list
  288. option-argument. The
  289. .IR qalter
  290. utility shall permit the repetition of characters, but shall not assign
  291. additional meaning to the repeated characters. An implementation may
  292. define other hold types. The conformance document for an implementation
  293. shall describe any additional hold types, how they are specified, their
  294. internal behavior, and how they affect the behavior of the utility.
  295. .RE
  296. .IP "\fB\-j\ \fIjoin_list\fR" 10
  297. Redefine which streams of the batch job are to be merged. The
  298. .IR qalter
  299. .BR \-j
  300. option shall accept a value for the
  301. .IR join_list
  302. option-argument that is a string of alphanumeric characters in the
  303. portable character set.
  304. .RS 10
  305. .P
  306. The
  307. .IR qalter
  308. utility shall accept a
  309. .IR join_list
  310. option-argument that consists of one or more of the characters
  311. .BR 'e'
  312. and
  313. .BR 'o' ,
  314. or the single character
  315. .BR 'n' .
  316. .P
  317. All of the other batch job output streams specified shall be merged
  318. into the output stream represented by the character listed first in the
  319. .IR join_list
  320. option-argument.
  321. .P
  322. For each unique character in the
  323. .IR join_list
  324. option-argument, the
  325. .IR qalter
  326. utility shall add a value to the
  327. .IR Join_Path
  328. attribute of the batch job as follows, each representing a different
  329. batch job stream to join:
  330. .IP "\fRe\fP" 6
  331. The standard error of the batch job (JOIN_STD_ERROR).
  332. .IP "\fRo\fP" 6
  333. The standard output of the batch job (JOIN_STD_OUTPUT).
  334. .P
  335. An existing
  336. .IR Join_Path
  337. attribute can be cleared by the join type:
  338. .IP "\fRn\fP" 6
  339. NO_JOIN
  340. .P
  341. If
  342. .BR 'n'
  343. is specified, then no files are joined. The
  344. .IR qalter
  345. utility shall consider it an error if any join type other than
  346. .BR 'n'
  347. is combined with join type
  348. .BR 'n' .
  349. .P
  350. Strictly conforming applications shall not repeat any of the characters
  351. .BR 'e' ,
  352. .BR 'o' ,
  353. or
  354. .BR 'n'
  355. within the
  356. .IR join_list
  357. option-argument. The
  358. .IR qalter
  359. utility shall permit the repetition of characters, but shall not assign
  360. additional meaning to the repeated characters.
  361. .P
  362. An implementation may define other join types. The conformance document
  363. for an implementation shall describe any additional batch job streams,
  364. how they are specified, their internal behavior, and how they affect
  365. the behavior of the utility.
  366. .RE
  367. .IP "\fB\-k\ \fIkeep_list\fR" 10
  368. Redefine which output of the batch job to retain on the execution host.
  369. .RS 10
  370. .P
  371. The
  372. .IR qalter
  373. .BR \-k
  374. option shall accept a value for the
  375. .IR keep_list
  376. option-argument that is a string of alphanumeric characters in the
  377. portable character set.
  378. .P
  379. The
  380. .IR qalter
  381. utility shall accept a
  382. .IR keep_list
  383. option-argument that consists of one or more of the characters
  384. .BR 'e'
  385. and
  386. .BR 'o' ,
  387. or the single character
  388. .BR 'n' .
  389. .P
  390. For each unique character in the
  391. .IR keep_list
  392. option-argument, the
  393. .IR qalter
  394. utility shall add a value to the
  395. .IR Keep_Files
  396. attribute of the batch job as follows, each representing a different
  397. batch job stream to keep:
  398. .IP "\fRe\fP" 6
  399. The standard error of the batch job (KEEP_STD_ERROR).
  400. .IP "\fRo\fP" 6
  401. The standard output of the batch job (KEEP_STD_OUTPUT).
  402. .P
  403. If both
  404. .BR 'e'
  405. and
  406. .BR 'o'
  407. are specified, then both files are retained. An existing
  408. .IR Keep_Files
  409. attribute can be cleared by the keep type:
  410. .IP "\fRn\fP" 6
  411. NO_KEEP
  412. .P
  413. If
  414. .BR 'n'
  415. is specified, then no files are retained. The
  416. .IR qalter
  417. utility shall consider it an error if any keep type other than
  418. .BR 'n'
  419. is combined with keep type
  420. .BR 'n' .
  421. .P
  422. Strictly conforming applications shall not repeat any of the characters
  423. .BR 'e' ,
  424. .BR 'o' ,
  425. or
  426. .BR 'n'
  427. within the
  428. .IR keep_list
  429. option-argument. The
  430. .IR qalter
  431. utility shall permit the repetition of characters, but shall not assign
  432. additional meaning to the repeated characters. An implementation may
  433. define other keep types. The conformance document for an implementation
  434. shall describe any additional keep types, how they are specified, their
  435. internal behavior, and how they affect the behavior of the utility.
  436. .RE
  437. .IP "\fB\-l\ \fIresource_list\fR" 10
  438. .br
  439. Redefine the resources that are allowed or required by the batch job.
  440. .RS 10
  441. .P
  442. The
  443. .IR qalter
  444. utility shall accept a
  445. .IR resource_list
  446. option-argument that conforms to the following syntax:
  447. .sp
  448. .RS 4
  449. .nf
  450. resource=value[,,resource=value,,...]
  451. .fi
  452. .P
  453. .RE
  454. .P
  455. The
  456. .IR qalter
  457. utility shall set one entry in the value of the
  458. .IR Resource_List
  459. attribute of the batch job for each resource listed in the
  460. .IR resource_list
  461. option-argument.
  462. .P
  463. Because the list of supported resource names might vary by batch
  464. server, the
  465. .IR qalter
  466. utility shall rely on the batch server to validate the resource names
  467. and associated values. See
  468. .IR "Section 3.3.3" ", " "Multiple Keyword-Value Pairs"
  469. for a means of removing
  470. .IR keyword =\c
  471. .IR value
  472. (and
  473. .IR value @\c
  474. .IR keyword )
  475. pairs and other general rules for list-oriented batch job attributes.
  476. .RE
  477. .IP "\fB\-m\ \fImail_options\fR" 10
  478. .br
  479. Redefine the points in the execution of the batch job at which the
  480. batch server is to send mail about a change in the state of the batch
  481. job.
  482. .RS 10
  483. .P
  484. The
  485. .IR qalter
  486. .BR \-m
  487. option shall accept a value for the
  488. .IR mail_options
  489. option-argument that is a string of alphanumeric characters in the
  490. portable character set.
  491. .P
  492. The
  493. .IR qalter
  494. utility shall accept a value for the
  495. .IR mail_options
  496. option-argument that is a string of one or more of the characters
  497. .BR 'e' ,
  498. .BR 'b' ,
  499. and
  500. .BR 'a' ,
  501. or the single character
  502. .BR 'n' .
  503. For each unique character in the
  504. .IR mail_options
  505. option-argument, the
  506. .IR qalter
  507. utility shall add a value to the
  508. .IR Mail_Users
  509. attribute of the batch job as follows, each representing a different
  510. time during the life of a batch job at which to send mail:
  511. .IP "\fRe\fP" 6
  512. MAIL_AT_EXIT
  513. .IP "\fRb\fP" 6
  514. MAIL_AT_BEGINNING
  515. .IP "\fRa\fP" 6
  516. MAIL_AT_ABORT
  517. .P
  518. If any of these characters are duplicated in the
  519. .IR mail_options
  520. option-argument, the duplicates shall be ignored.
  521. .P
  522. An existing
  523. .IR Mail_Points
  524. attribute can be cleared by the mail type:
  525. .IP "\fRn\fP" 6
  526. NO_MAIL
  527. .P
  528. If
  529. .BR 'n'
  530. is specified, then mail is not sent. The
  531. .IR qalter
  532. utility shall consider it an error if any mail type other than
  533. .BR 'n'
  534. is combined with mail type
  535. .BR 'n' .
  536. Strictly conforming applications shall not repeat any of the characters
  537. .BR 'e' ,
  538. .BR 'b' ,
  539. .BR 'a' ,
  540. or
  541. .BR 'n'
  542. within the
  543. .IR mail_options
  544. option-argument. The
  545. .IR qalter
  546. utility shall permit the repetition of characters but shall not assign
  547. additional meaning to the repeated characters.
  548. .P
  549. An implementation may define other mail types. The conformance document
  550. for an implementation shall describe any additional mail types, how
  551. they are specified, their internal behavior, and how they affect the
  552. behavior of the utility.
  553. .RE
  554. .IP "\fB\-M\ \fImail_list\fR" 10
  555. Redefine the list of users to which the batch server that executes the
  556. batch job is to send mail, if the batch server sends mail about the
  557. batch job.
  558. .RS 10
  559. .P
  560. The syntax of the
  561. .IR mail_list
  562. option-argument is unspecified. If the implementation of the
  563. .IR qalter
  564. utility uses a name service to locate users, the utility shall accept
  565. the syntax used by the name service.
  566. .P
  567. If the implementation of the
  568. .IR qalter
  569. utility does not use a name service to locate users, the implementation
  570. shall accept the following syntax for user names:
  571. .sp
  572. .RS 4
  573. .nf
  574. mail_address[,,mail_address,,...]
  575. .fi
  576. .P
  577. .RE
  578. .P
  579. The interpretation of
  580. .IR mail_address
  581. is implementation-defined.
  582. .P
  583. The
  584. .IR qalter
  585. utility shall set the
  586. .IR Mail_Users
  587. attribute of the batch job to the value of the
  588. .IR mail_list
  589. option-argument.
  590. .RE
  591. .IP "\fB\-N\ \fIname\fR" 10
  592. Redefine the name of the batch job.
  593. .RS 10
  594. .P
  595. The
  596. .IR qalter
  597. .BR \-N
  598. option shall accept a value for the
  599. .IR name
  600. option-argument that is a string of up to 15 alphanumeric characters in
  601. the portable character set where the first character is alphabetic.
  602. .P
  603. The syntax of the
  604. .IR name
  605. option-argument is unspecified.
  606. .P
  607. The
  608. .IR qalter
  609. utility shall set the
  610. .IR Job_Name
  611. attribute of the batch job to the value of the
  612. .IR name
  613. option-argument.
  614. .RE
  615. .IP "\fB\-o\ \fIpath_name\fR" 10
  616. .br
  617. Redefine the path for the standard output of the batch job.
  618. .RS 10
  619. .P
  620. The
  621. .IR qalter
  622. utility shall accept a
  623. .IR path_name
  624. option-argument that conforms to the syntax of the
  625. .IR path_name
  626. element defined in the System Interfaces volume of POSIX.1\(hy2017, which can be preceded by a host name
  627. element of the form
  628. .IR hostname :.
  629. .P
  630. If the
  631. .IR path_name
  632. option-argument constitutes an absolute pathname, the
  633. .IR qalter
  634. utility shall set the
  635. .IR Output_Path
  636. attribute of the batch job to the value of the
  637. .IR path_name
  638. option-argument.
  639. .P
  640. If the
  641. .IR path_name
  642. option-argument constitutes a relative pathname and no host name
  643. element is specified, the
  644. .IR qalter
  645. utility shall set the
  646. .IR Output_Path
  647. attribute of the batch job to the absolute pathname derived by
  648. expanding the
  649. .IR path_name
  650. option-argument relative to the current directory of the process that
  651. executes the
  652. .IR qalter
  653. utility.
  654. .P
  655. If the
  656. .IR path_name
  657. option-argument constitutes a relative pathname and a host name
  658. element is specified, the
  659. .IR qalter
  660. utility shall set the
  661. .IR Output_Path
  662. attribute of the batch job to the value of the
  663. .IR path_name
  664. option-argument without any expansion of the pathname.
  665. .P
  666. If the
  667. .IR path_name
  668. option-argument does not include a host name element, the
  669. .IR qalter
  670. utility shall prefix the pathname in the
  671. .IR Output_Path
  672. attribute with
  673. .IR hostname :,
  674. where
  675. .IR hostname
  676. is the name of the host upon which the
  677. .IR qalter
  678. utility is being executed.
  679. .RE
  680. .IP "\fB\-p\ \fIpriority\fR" 10
  681. Redefine the priority of the batch job.
  682. .RS 10
  683. .P
  684. The
  685. .IR qalter
  686. utility shall accept a value for the priority option-argument that
  687. conforms to the syntax for signed decimal integers, and which is not
  688. less than \-1\|024 and not greater than 1\|023.
  689. .P
  690. The
  691. .IR qalter
  692. utility shall set the
  693. .IR Priority
  694. attribute of the batch job to the value of the
  695. .IR priority
  696. option-argument.
  697. .RE
  698. .IP "\fB\-r\ \fRy\fR|\fRn\fR" 10
  699. Redefine whether the batch job is rerunnable.
  700. .RS 10
  701. .P
  702. If the value of the option-argument is
  703. .BR 'y' ,
  704. the
  705. .IR qalter
  706. utility shall set the
  707. .IR Rerunable
  708. attribute of the batch job to TRUE.
  709. .P
  710. If the value of the option-argument is
  711. .BR 'n' ,
  712. the
  713. .IR qalter
  714. utility shall set the
  715. .IR Rerunable
  716. attribute of the batch job to FALSE.
  717. .P
  718. The
  719. .IR qalter
  720. utility shall consider it an error if any character other than
  721. .BR 'y'
  722. or
  723. .BR 'n'
  724. is specified in the option-argument.
  725. .RE
  726. .IP "\fB\-S\ \fIpath_name_list\fR" 10
  727. .br
  728. Redefine the shell that interprets the script at the destination
  729. system.
  730. .RS 10
  731. .P
  732. The
  733. .IR qalter
  734. utility shall accept a
  735. .IR path_name_list
  736. option-argument that conforms to the following syntax:
  737. .sp
  738. .RS 4
  739. .nf
  740. pathname[@host][,pathname[@host],...]
  741. .fi
  742. .P
  743. .RE
  744. .P
  745. The
  746. .IR qalter
  747. utility shall accept only one pathname that is missing a corresponding
  748. host name. The
  749. .IR qalter
  750. utility shall allow only one pathname per named host.
  751. .P
  752. The
  753. .IR qalter
  754. utility shall add a value to the
  755. .IR Shell_Path_List
  756. attribute of the batch job for each entry in the
  757. .IR path_name_list
  758. option-argument. See
  759. .IR "Section 3.3.3" ", " "Multiple Keyword-Value Pairs"
  760. for a means of removing
  761. .IR keyword =\c
  762. .IR value
  763. (and
  764. .IR value @\c
  765. .IR keyword )
  766. pairs and other general rules for list-oriented batch job attributes.
  767. .RE
  768. .IP "\fB\-u\ \fIuser_list\fR" 10
  769. Redefine the user name under which the batch job is to run at the
  770. destination system.
  771. .RS 10
  772. .P
  773. The
  774. .IR qalter
  775. utility shall accept a
  776. .IR user_list
  777. option-argument that conforms to the following syntax:
  778. .sp
  779. .RS 4
  780. .nf
  781. username[@host][,,username[@host],,...]
  782. .fi
  783. .P
  784. .RE
  785. .P
  786. The
  787. .IR qalter
  788. utility shall accept only one user name that is missing a corresponding
  789. host name. The
  790. .IR qalter
  791. utility shall accept only one user name per named host.
  792. .P
  793. The
  794. .IR qalter
  795. utility shall add a value to the
  796. .IR User_List
  797. attribute of the batch job for each entry in the
  798. .IR user_list
  799. option-argument. See
  800. .IR "Section 3.3.3" ", " "Multiple Keyword-Value Pairs"
  801. for a means of removing
  802. .IR keyword =\c
  803. .IR value
  804. (and
  805. .IR value @\c
  806. .IR keyword )
  807. pairs and other general rules for list-oriented batch job attributes.
  808. .RE
  809. .SH OPERANDS
  810. The
  811. .IR qalter
  812. utility shall accept one or more operands that conform to the syntax
  813. for a batch
  814. .IR job_identifier
  815. (see
  816. .IR "Section 3.3.1" ", " "Batch Job Identifier").
  817. .SH STDIN
  818. Not used.
  819. .SH "INPUT FILES"
  820. None.
  821. .SH "ENVIRONMENT VARIABLES"
  822. The following environment variables shall affect the execution of
  823. .IR qalter :
  824. .IP "\fILANG\fP" 10
  825. Provide a default value for the internationalization variables that are
  826. unset or null. (See the Base Definitions volume of POSIX.1\(hy2017,
  827. .IR "Section 8.2" ", " "Internationalization Variables"
  828. the precedence of internationalization variables used to determine the
  829. values of locale categories.)
  830. .IP "\fILC_ALL\fP" 10
  831. If set to a non-empty string value, override the values of all the
  832. other internationalization variables.
  833. .IP "\fILC_CTYPE\fP" 10
  834. Determine the locale for the interpretation of sequences of bytes of
  835. text data as characters (for example, single-byte as opposed to
  836. multi-byte characters in arguments).
  837. .IP "\fILC_MESSAGES\fP" 10
  838. .br
  839. Determine the locale that should be used to affect the format and
  840. contents of diagnostic messages written to standard error.
  841. .IP "\fILOGNAME\fP" 10
  842. Determine the login name of the user.
  843. .IP "\fITZ\fP" 10
  844. Determine the timezone used to interpret the
  845. .IR date-time
  846. option-argument. If
  847. .IR TZ
  848. is unset or null, an unspecified default timezone shall be used.
  849. .SH "ASYNCHRONOUS EVENTS"
  850. Default.
  851. .SH STDOUT
  852. None.
  853. .SH STDERR
  854. The standard error shall be used only for diagnostic messages.
  855. .SH "OUTPUT FILES"
  856. None.
  857. .SH "EXTENDED DESCRIPTION"
  858. None.
  859. .SH "EXIT STATUS"
  860. The following exit values shall be returned:
  861. .IP "\00" 6
  862. Successful completion.
  863. .IP >0 6
  864. An error occurred.
  865. .SH "CONSEQUENCES OF ERRORS"
  866. In addition to the default behavior, the
  867. .IR qalter
  868. utility shall not be required to write a diagnostic message to standard
  869. error when the error reply received from a batch server indicates that
  870. the batch
  871. .IR job_identifier
  872. does not exist on the server. Whether or not the
  873. .IR qalter
  874. utility attempts to locate the batch job on other batch servers is
  875. implementation-defined.
  876. .LP
  877. .IR "The following sections are informative."
  878. .SH "APPLICATION USAGE"
  879. None.
  880. .SH EXAMPLES
  881. None.
  882. .SH RATIONALE
  883. The
  884. .IR qalter
  885. utility allows users to change the attributes of a batch job.
  886. .P
  887. As a means of altering a queued job, the
  888. .IR qalter
  889. utility is superior to deleting and requeuing the batch job insofar as
  890. an altered job retains its place in the queue with some traditional
  891. selection algorithms. In addition, the
  892. .IR qalter
  893. utility is both shorter and simpler than a sequence of
  894. .IR qdel
  895. and
  896. .IR qsub
  897. utilities.
  898. .P
  899. The result of an attempt on the part of a user to alter a batch job in
  900. a RUNNING state is implementation-defined because a batch job in the
  901. RUNNING state will already have opened its output files and otherwise
  902. performed any actions indicated by the options in effect at the time
  903. the batch job began execution.
  904. .P
  905. The options processed by the
  906. .IR qalter
  907. utility are identical to those of the
  908. .IR qsub
  909. utility, with a few exceptions:
  910. .BR \-V ,
  911. .BR \-v ,
  912. and
  913. .BR \-q .
  914. The
  915. .BR \-V
  916. and
  917. .BR \-v
  918. are inappropriate for the
  919. .IR qalter
  920. utility, since they capture potentially transient environment
  921. information from the submitting process. The
  922. .BR \-q
  923. option would specify a new queue, which would largely negate the
  924. previously stated advantage of using
  925. .IR qalter ;
  926. furthermore, the
  927. .IR qmove
  928. utility provides a superior means of moving jobs.
  929. .P
  930. Each of the following paragraphs provides the rationale for a
  931. .IR qalter
  932. option.
  933. .P
  934. Additional rationale concerning these options can be found in the
  935. rationale for the
  936. .IR qsub
  937. utility.
  938. .P
  939. The
  940. .BR \-a
  941. option allows users to alter the date and time at which a batch job
  942. becomes eligible to run.
  943. .P
  944. The
  945. .BR \-A
  946. option allows users to change the account that will be charged for the
  947. resources consumed by the batch job. Support for the
  948. .BR \-A
  949. option is mandatory for conforming implementations of
  950. .IR qalter ,
  951. even though support of accounting is optional for servers. Whether or
  952. not to support accounting is left to the implementor of the server, but
  953. mandatory support of the
  954. .BR \-A
  955. option assures users of a consistent interface and allows them to
  956. control accounting on servers that support accounting.
  957. .P
  958. The
  959. .BR \-c
  960. option allows users to alter the checkpointing interval of a batch
  961. job. A checkpointing system, which is not defined by POSIX.1\(hy2008, allows
  962. recovery of a batch job at the most recent checkpoint in the event of a
  963. crash. Checkpointing is typically used for jobs that consume expensive
  964. computing time or must meet a critical schedule. Users should be
  965. allowed to make the tradeoff between the overhead of checkpointing and
  966. the risk to the timely completion of the batch job; therefore, this volume of POSIX.1\(hy2017
  967. provides the checkpointing interval option. Support for checkpointing
  968. is optional for servers.
  969. .P
  970. The
  971. .BR \-e
  972. option allows users to alter the name and location of the standard
  973. error stream written by a batch job. However, the path of the standard
  974. error stream is meaningless if the value of the
  975. .IR Join_Path
  976. attribute of the batch job is TRUE.
  977. .P
  978. The
  979. .BR \-h
  980. option allows users to set the hold type in the
  981. .IR Hold_Types
  982. attribute of a batch job. The
  983. .IR qhold
  984. and
  985. .IR qrls
  986. utilities add or remove hold types to the
  987. .IR Hold_Types
  988. attribute, respectively. The
  989. .BR \-h
  990. option has been modified to allow for implementation-defined hold
  991. types.
  992. .P
  993. The
  994. .BR \-j
  995. option allows users to alter the decision to join (merge) the standard
  996. error stream of the batch job with the standard output stream of the
  997. batch job.
  998. .P
  999. The
  1000. .BR \-l
  1001. option allows users to change the resource limits imposed on a batch
  1002. job.
  1003. .P
  1004. The
  1005. .BR \-m
  1006. option allows users to modify the list of points in the life of a batch
  1007. job at which the designated users will receive mail notification.
  1008. .P
  1009. The
  1010. .BR \-M
  1011. option allows users to alter the list of users who will receive
  1012. notification about events in the life of a batch job.
  1013. .P
  1014. The
  1015. .BR \-N
  1016. option allows users to change the name of a batch job.
  1017. .P
  1018. The
  1019. .BR \-o
  1020. option allows users to alter the name and path to which the standard
  1021. output stream of the batch job will be written.
  1022. .P
  1023. The
  1024. .BR \-P
  1025. option allows users to modify the priority of a batch job. Support for
  1026. priority is optional for batch servers.
  1027. .P
  1028. The
  1029. .BR \-r
  1030. option allows users to alter the rerunability status of a batch job.
  1031. .P
  1032. The
  1033. .BR \-S
  1034. option allows users to change the name and location of the shell image
  1035. that will be invoked to interpret the script of the batch job. This
  1036. option has been modified to allow a list of shell name and locations
  1037. associated with different hosts.
  1038. .P
  1039. The
  1040. .BR \-u
  1041. option allows users to change the user identifier under which the batch
  1042. job will execute.
  1043. .P
  1044. The
  1045. .IR job_identifier
  1046. operand syntax is provided so that the user can differentiate between
  1047. the originating and destination (or executing) batch server. These may
  1048. or may not be the same. The .\c
  1049. .IR server_name
  1050. portion identifies the originating batch server, while the @\c
  1051. .IR server
  1052. portion identifies the destination batch server.
  1053. .P
  1054. Historically, the
  1055. .IR qalter
  1056. utility has been a component of the Network Queuing System (NQS), the
  1057. existing practice from which this utility has been derived.
  1058. .SH "FUTURE DIRECTIONS"
  1059. The
  1060. .IR qalter
  1061. utility may be removed in a future version.
  1062. .SH "SEE ALSO"
  1063. .IR "Chapter 3" ", " "Batch Environment Services",
  1064. .IR "\fIqdel\fR\^",
  1065. .IR "\fIqhold\fR\^",
  1066. .IR "\fIqmove\fR\^",
  1067. .IR "\fIqrls\fR\^",
  1068. .IR "\fIqsub\fR\^",
  1069. .IR "\fItouch\fR\^"
  1070. .P
  1071. The Base Definitions volume of POSIX.1\(hy2017,
  1072. .IR "Chapter 8" ", " "Environment Variables",
  1073. .IR "Section 12.2" ", " "Utility Syntax Guidelines"
  1074. .\"
  1075. .SH COPYRIGHT
  1076. Portions of this text are reprinted and reproduced in electronic form
  1077. from IEEE Std 1003.1-2017, Standard for Information Technology
  1078. -- Portable Operating System Interface (POSIX), The Open Group Base
  1079. Specifications Issue 7, 2018 Edition,
  1080. Copyright (C) 2018 by the Institute of
  1081. Electrical and Electronics Engineers, Inc and The Open Group.
  1082. In the event of any discrepancy between this version and the original IEEE and
  1083. The Open Group Standard, the original IEEE and The Open Group Standard
  1084. is the referee document. The original Standard can be obtained online at
  1085. http://www.opengroup.org/unix/online.html .
  1086. .PP
  1087. Any typographical or formatting errors that appear
  1088. in this page are most likely
  1089. to have been introduced during the conversion of the source files to
  1090. man page format. To report such errors, see
  1091. https://www.kernel.org/doc/man-pages/reporting_bugs.html .