~ubuntu-branches/ubuntu/utopic/gridengine/utopic

<A HREF="../htmlman3/drmaa_set_attribute.html">drmaa_set_attribute(3)</A> and <A HREF="../htmlman3/drmaa_get_attribute.html">drmaa_get_attribute(3)</A> for set-

ting and inspecting non-vector attributes.

drmaa_get_vector_attribute_names()

The drmaa_get_vector_attribute_names() function returns into

values a DRMAA names string vector containing the set of

supported vector DRMAA job template attribute names. The set

includes supported DRMAA reserved attribute names and Grid

Engine native attribute names. The names in the names string

vector can be extracted using <A HREF="../htmlman3/drmaa_get_next_attr_name.html">drmaa_get_next_attr_name(3)</A>.

The caller is responsible for releasing the names string

vector returned into values using

<A HREF="../htmlman3/drmaa_release_attr_names.html">drmaa_release_attr_names(3)</A>. Use

<A HREF="../htmlman3/drmaa_set_vector_attribute.html">drmaa_set_vector_attribute(3)</A> and

<A HREF="../htmlman3/drmaa_get_vector_attribute.html">drmaa_get_vector_attribute(3)</A> for setting and inspecting

vector attributes.

drmaa_get_next_attr_name()

Each time drmaa_get_next_attr_name() is called it returns

into the buffer, value, up to value_len bytes of the next

entry stored in the DRMAA names string vector, values. With

the DRMAA 1.0 library, once the names list has been

exhausted, DRMAA_ERRNO_NO_MORE_ELEMENTS is returned. With

the DRMAA 0.95 library, once the names list has been

exhausted, DRMAA_ERRNO_INVALID_ATTRIBUTE_VALUE is returned.

In order to use the DRMAA 0.95 library, you must define the

DRMAA_95 macro, either in your application directly or

through a compiler flag, such as -DDRMAA_95.

drmaa_get_num_attr_names()

The drmaa_get_num_attr_names() returns into size the number

of entries in the DRMAA names string vector. This function

is only available in the 1.0 implementation.

drmaa_release_attr_names()

The drmaa_release_attr_names() function releases all

resources associated with the DRMAA names string vector,

values.

Attribute Priorities

DRMAA job template attributes can be set from six different

sources. In order of precedence, from lowest to highest,

100

these are: options set by DRMAA automatically by default,

101

options set in the <A HREF="../htmlman5/sge_request.html">sge_request(5)</A> file(s), options set in

102

the script file, options set by the drmaa_job_category

103

attribute, options set by the drmaa_native_specification

104

attribute, and options set through other DRMAA attributes.

105

106

By default DRMAA sets four options for all jobs. These are

107

"-p 0", "-b yes", "-shell no", and "-w e". This means that

108

by default, all jobs will have priority 0, all jobs will be

109

treated as binary, i.e. no scripts args will be parsed, all

110

jobs will be executed without a wrapper shell, and jobs

111

which are unschedulable will cause a submit error.

112

113

The <A HREF="../htmlman5/sge_request.html">sge_request(5)</A> file, found in the

114

$SGE_ROOT/$SGE_CELL/common directory, may contain options to

115

be applied to all jobs. The .sge_request file found in the

116

user's home directory or the current working directory may

117

also contain options to be applied to certain jobs. See

118

<A HREF="../htmlman5/sge_request.html">sge_request(5)</A> for more information.

119

120

If the <A HREF="../htmlman5/sge_request.html">sge_request(5)</A> file contains "-b no" or if the

121

drmaa_native_specification attribute is set and contains "-b

122

no", the script file will be parsed for in-line arguments.

123

Otherwise, no scripts args will be interpreted. See <A HREF="../htmlman1/qsub.html">qsub(1)</A>

124

for more information.

125

126

If the drmaa_job_category attribute is set, and the category

127

it points to exists in one of the <A HREF="../htmlman5/qtask.html">qtask(5)</A> files, the

128

options associated with that category will be applied to the

129

job template. See <A HREF="../htmlman5/qtask.html">qtask(5)</A> and the drmaa_job_category

130

attribute below for more information.

131

132

If the drmaa_native_specification attribute is set, all

133

options contained therein will be applied to the job tem-

134

plate. See the drmaa_native_specification below for more

135

information.

136

137

Other DRMAA attributes will override any previous settings.

138

For example, if the sge_request file contains "-j y", but

139

the drmaa_join_files attribute is set to "n", the ultimate

140

result is that the input and output files will remain

141

separate.

142

143

For various reasons, some options are silently ignored by

144

DRMAA. Setting any of these options will have no effect.

145

The ignored options are: -cwd, -help, -t, -verify, -w w, and

146

-w v. The -cwd option can be reenabled by setting the

147

environment variable, SGE_DRMAA_ALLOW_CWD. However, the

148

-cwd option is not thread safe and should not be used in a

149

multi-threaded context.

150

151

Attribute Correlations

152

The following DRMAA attributes correspond to the following

153

<A HREF="../htmlman1/qsub.html">qsub(1)</A> options:

154

155

DRMAA Attribute qsub Option

156

-------------------------------------------------------

157

drmaa_remote_command script file

158

drmaa_v_argv script file args

159

drmaa_js_state = "drmaa_hold" -h

160

drmaa_v_env -v

161

drmaa_wd = $PWD -cwd

162

drmaa_job_category (qtsch qtask)*

163

drmaa_native_specification ALL*

164

drmaa_v_email -M

165

drmaa_block_email = "1" -m n

166

drmaa_start_time -a

167

drmaa_job_name -N

168

drmaa_input_path -i

169

drmaa_output_path -o

170

drmaa_error_path -e

171

drmaa_join_files -j

172

drmaa_transfer_files (prolog and epilog)*

173

174

* See the individual attribute description below

175

176

DRMAA JOB TEMPLATE ATTRIBUTES

177

drmaa_remote_command - "<remote_command>"

178

Specifies the remote command to execute. The remote_command

179

must be the path of an executable that is available at the

180

job's execution host. If the path is relative, it is

181

assumed to be relative to the working directory, usually set

182

through the drmaa_wd attribute. If working directory is not

183

set, the path is assumed to be relative to the user's home

184

directory.

185

186

The file pointed to by remote_command may either be an exe-

187

cutable binary or an executable script. If a script, it

188

must include the path to the shell in a #! line at the

189

beginning of the script. By default, the remote command

190

will be executed directly, as by <A HREF="../htmlman2/exec.html">exec(2)</A>. To have the

191

remote command executed in a shell, such as to preserve

192

environment settings, use the drmaa_native_specification

193

attribute to include the "-shell yes" option. Jobs which

194

are executed by a wrapper shell fail differently from jobs

195

which are executed directly. When a job which contains a

196

user error, such as an invalid path to the executable, is

197

executed by a wrapper shell, the job will execute success-

198

fully, but exit with a return code of 1. When a job which

199

contains such an error is executed directly, it will enter

200

the DRMAA_PS_FAILED state upon execution.

201

202

drmaa_js_state - "{drmaa_hold|drmaa_active}"

203

Specifies the job state at submission. The string values

204

'drmaa_hold' and 'drmaa_active' are supported. When

205

'drmaa_active' is used the job is submitted in a runnable

206

state. When 'drmaa_hold' is used the job is submitted in

207

user hold state (either DRMAA_PS_USER_ON_HOLD or

208

DRMAA_PS_USER_SYSTEM_ON_HOLD). This attribute is largely

209

equivalent to the <A HREF="../htmlman1/qsub.html">qsub(1)</A> submit option '-h'.

210

211

drmaa_wd - "<directory_name>"

212

Specifies the directory name where the job will be executed.

213

A '$drmaa_hd_ph$' placeholder at the beginning of the

214

directory_name denotes the remaining string portion as a

215

relative directory name that is resolved relative to the job

216

user's home directory at the execution host. When the DRMAA

217

job template is used for bulk job submission (see also

218

<A HREF="../htmlman3/drmaa_run_bulk_job.html">drmaa_run_bulk_job(3)</A>) the '$drmaa_incr_ph$' placeholder can

219

be used at any position within directory_name to cause a

220

substitution with the parametric job's index. The

221

directory_name must be specified in a syntax that is common

222

at the host where the job is executed. If set to a relative

223

path and no placeholder is used, a path relative to the

224

user's home directory is assumed. If not set, the working

225

directory will default to the user's home directory. If set

226

and the given directory does not exist the job will enter

227

the DRMAA_PS_FAILED state when run.

228

229

Note that the working directory path is the path on the exe-

230

cution host. If binary mode is disabled, an attempt to find

231

the job script will be made, relative to the working direc-

232

tory path. That means that the path to the script must be

233

the same on both the submission and execution hosts.

234

235

drmaa_job_name - "<job_name>"

236

Specifies the job's name. Setting the job name is equivalent

237

to use of <A HREF="../htmlman1/qsub.html">qsub(1)</A> submit option '-N' with job_name as option

238

argument.

239

240

drmaa_input_path - "[<hostname>]:<file_path>"

241

Specifies the standard input of the job. Unless set else-

242

where, if not explicitly set in the job template, the job is

243

started with an empty input stream. If the standard input is

244

set it specifies the network path of the job's input stream

245

file.

246

247

When the 'drmaa_transfer_files' job template attribute is

248

supported and contains the character 'i', the input file

249

will be fetched by Grid Engine from the specified host or

250

from the submit host if no hostname is specified. When the

251

'drmaa_transfer_files' job template attribute is not sup-

252

ported or does not contain the character 'i', the input file

253

is always expected at the host where the job is executed

254

regardless of any hostname specified.

255

256

If the DRMAA job template will be used for bulk job submis-

257

sion, (See also <A HREF="../htmlman3/drmaa_run_bulk_job.html">drmaa_run_bulk_job(3)</A>) the '$drmaa_incr_ph$'

258

placeholder can be used at any position within file_path to

259

cause a substitution with the parametric job's index. A

260

'$drmaa_hd_ph$' placeholder at the beginning of file_path

261

denotes the remaining portion of the file_path as a relative

262

file specification resolved relative to the job user's home

263

directory at the host where the file is located. A

264

'$drmaa_wd_ph$' placeholder at the beginning of file_path

265

denotes the remaining portion of the file_path as a relative

266

file specification resolved relative to the job's working

267

directory at the host where the file is located. The

268

file_path must be specified in a syntax that is common at

269

the host where the file is located. If set and the file

270

can't be read the job enters the state DRMAA_PS_FAILED.

271

272

drmaa_output_path - "[<hostname>]:<file_path>"

273

Specifies the standard output of the job. If not explicitly

274

set in the job template, the whereabouts of the job's output

275

stream is not defined. If set, this attribute specifies the

276

network path of the job's output stream file.

277

278

When the 'drmaa_transfer_files' job template attribute is

279

supported and contains the character 'o', the output file

280

will be transferred by Grid Engine to the specified host or

281

to the submit host if no hostname is specified. When the

282

'drmaa_transfer_files' job template attribute is not sup-

283

ported or does not contain the character 'o', the output

284

file is always kept at the host where the job is executed

285

regardless of any hostname specified.

286

287

If the DRMAA job template will be used for of bulk job sub-

288

mission (see also <A HREF="../htmlman3/drmaa_run_bulk_job.html">drmaa_run_bulk_job(3)</A>) the

289

'$drmaa_incr_ph$' placeholder can be used at any position

290

within the file_path to cause a substitution with the

291

parametric job's index. A '$drmaa_hd_ph$' placeholder at the

292

beginning of file_path denotes the remaining portion of the

293

file_path as a relative file specification resolved relative

294

to the job user's home directory at the host where the file

295

is located. A '$drmaa_wd_ph$' placeholder at the beginning

296

of the file_path denotes the remaining portion of file_path

297

as a relative file specification resolved relative to the

298

job's working directory at the host where the file is

299

located. The file_path must be specified in a syntax that is

300

common at the host where the file is located. If set and the

301

file can't be written before execution the job enters the

302

state DRMAA_PS_FAILED.

303

304

drmaa_error_path - "[<hostname>]:<file_path>"

305

Specifies the standard error of the job. If not explicitly

306

set in the job template, the whereabouts of the job's error

307

stream is not defined. If set, this attribute specifies the

308

network path of the job's error stream file.

309

310

When the 'drmaa_transfer_files' job template attribute is

311

supported and contains the character 'e', the output file

312

will be transferred by Grid Engine to the specified host or

313

to the submit host if no hostname is specified. When the

314

'drmaa_transfer_files' job template attribute is not sup-

315

ported or does not contain the character 'e', the error file

316

is always kept at the host where the job is executed

317

regardless of any hostname specified.

318

319

If the DRMAA job template will be used for of bulk job sub-

320

mission (see also <A HREF="../htmlman3/drmaa_run_bulk_job.html">drmaa_run_bulk_job(3)</A>) the

321

'$drmaa_incr_ph$' placeholder can be used at any position

322

within the file_path to cause a substitution with the

323

parametric job's index. A '$drmaa_hd_ph$' placeholder at the

324

beginning of the file_path denotes the remaining portion of

325

the file_path as a relative file specification resolved

326

relative to the job user's home directory at the host where

327

the file is located. A '$drmaa_wd_ph$' placeholder at the

328

beginning of the file_path denotes the remaining portion of

329

the file_path as a relative file specification resolved

330

relative to the job's working directory at the host where

331

the file is located. The file_path must be specified in a

332

syntax that is common at the host where the file is located.

333

If set and the file can't be written before execution the

334

job enters the state DRMAA_PS_FAILED. The attribute name is

335

drmaa_error_path.

336

337

338

drmaa_join_files - "{y|n}"

339

Specifies if the job's error stream should be intermixed

340

with the output stream. If not explicitly set in the job

341

template the attribute defaults to 'n'. Either 'y' or 'n'

342

can be specified. If 'y' is specified Grid Engine will

343

ignore the value of the 'drmaa_error_path' job template

344

attribute and intermix the standard error stream with the

345

standard output stream as specified with

346

'drmaa_output_path'.

347

348

drmaa_v_argv - "argv1 argv2 ..."

349

Specifies the arguments to the job.

350

351

drmaa_job_category - "<category>"

352

Specifies the DRMAA job category. The category string is

353

used by Grid Engine as a reference into the <A HREF="../htmlman5/qtask.html">qtask(5)</A> file.

354

Certain <A HREF="../htmlman1/qsub.html">qsub(1)</A> options used in the referenced qtask file

355

line are applied to the job template before submission to

356

allow site-specific resolving of resources and/or policies.

357

The cluster qtask file, the local qtask file, and the user

358

qtask file are searched. Job settings resulting from job

359

template category are overridden by settings resulting from

360

the job template drmaa_native_specification attribute as

361

well as by explicit DRMAA job template settings.

362

363

In order to avoid collisions with command names in the qtask

364

files, it is recommended that DRMAA job category names take

365

the form: <category_name>.cat.

366

367

The options -help, -t, -verify, and -w w|v are ignored. The

368

-cwd option is ignored unless the $SGE_DRMAA_ALLOW_CWD

369

environment variable is set.

370

371

drmaa_native_specification - "<native_specification>"

372

Specifies Grid Engine native <A HREF="../htmlman1/qsub.html">qsub(1)</A> options which will be

373

interpreted as part of the DRMAA job template. All options

374

available to <A HREF="../htmlman1/qsub.html">qsub(1)</A> command may be used in the

375

native_specification, except for -help, -t, -verify, and -w

376

w|v. The -cwd option may only be used if the

377

SGE_DRMAA_ALLOW_CWD environment variable is set. This is

378

because the current parsing algorithm for -cwd is not

379

thread-safe. Options set in the native specification will

380

be overridden by the corresponding DRMAA attributes. See

381

<A HREF="../htmlman1/qsub.html">qsub(1)</A> for more information on qsub options.

382

383

drmaa_v_env - "<name1>=<value1> <name2>=<value2> ...

384

Specifies the job environment. Each environment value

385

defines the remote environment. The value overrides the

386

remote environment values if there is a collision.

387

388

drmaa_v_email - "<email1> <email2> ...

389

Specifies e-mail addresses that are used to report the job

390

completion and status.

391

392

drmaa_block_email - "{0|1}"

393

Specifies whether e-mail sending shall blocked or not. By

394

default email is not sent. If, however, a setting in a

395

cluster or user settings file or the email in association

396

with job events, the 'drmaa_block_email' attribute will

397

override that setting, causing no email to be sent.

398

399

drmaa_start_time - "[[[[CC]YY/]MM/]DD] hh:mm[:ss] [{-|+}UU:uu]"

400

Specifies the earliest time when the job may be eligible to

401

be run where

402

403

CC is the first two digits of the year (century-1)

404

YY is the last two digits of the year

405

MM is the two digits of the month [01,12]

406

DD is the two digit day of the month [01,31]

407

hh is the two digit hour of the day [00,23]

408

mm is the two digit minute of the day [00,59]

409

ss is the two digit second of the minute [00,61]

410

UU is the two digit hours since (before) UTC

411

uu is the two digit minutes since (before) UTC

412

413

If the optional UTC-offset is not specified, the offset

414

associated with the local timezone will be used. If the day

415

(DD) is not specified, the current day will be used unless

416

the specified hour:mm:ss has already elapsed, in which case

417

the next day will be used. Similarly for month (MM), year

418

(YY), and century-1 (CC). Example: The time: Sep 3 4:47:27

419

PM PDT 2002, could be represented as: 2002/09/03 16:47:27

420

-07:00.

421

422

drmaa_transfer_files - "[i][o][e]"

423

Specifies, which of the standard I/O files (stdin, stdout

424

and stderr) are to be transferred to/from the execution

425

host. If not set, defaults to "". Any combination of 'e',

426

'i' and 'o' may be specified. See drmaa_input_path,

427

drmaa_output_path and drmaa_error_path for information about

428

how to specify the standard input file, standard output file

429

and standard error file. The file transfer mechanism itself

430

must be configured by the administrator (see <A HREF="../htmlman5/sge_conf.html">sge_conf(5)</A> ).

431

When it is configured, the administrator has to enable

432

drmaa_transfer_files. If it is not configured,

433

"drmaa_transfer_files" is not enabled and can't be used.

434

435

ENVIRONMENTAL VARIABLES

436

SGE_DRMAA_ALLOW_CWD

437

Enables the parsing of the -cwd option from

438

the sge_request file(s), job category, and/or

439

the native specification attribute. This

440

option is disabled by default because the

441

algorithm for parsing the -cwd option is not

442

thread-safe.

443

444

SGE_ROOT Specifies the location of the Grid Engine

445

standard configuration files.

446

447

SGE_CELL If set, specifies the default Grid Engine

448

cell to be used. To address a Grid Engine

449

cell Grid Engine uses (in the order of pre-

450

cedence):

451

452

The name of the cell specified in the

453

environment variable SGE_CELL, if it is

454

set.

455

456

The name of the default cell, i.e.

457

default.

458

459

460

SGE_DEBUG_LEVEL

461

If set, specifies that debug information

462

should be written to stderr. In addition the

463

level of detail in which debug information is

464

generated is defined.

465

466

SGE_QMASTER_PORT

467

If set, specifies the tcp port on which

468

<A HREF="../htmlman8/sge_qmaster.html">sge_qmaster(8)</A> is expected to listen for com-

469

munication requests. Most installations will

470

use a services map entry instead to define

471

that port.

472

473

474

RETURN VALUES

475

Upon successful completion, drmaa_get_attribute_names(),

476

drmaa_get_vector_attribute_names(), and

477

drmaa_get_next_attr_name() return DRMAA_ERRNO_SUCCESS. Other

478

values indicate an error. Up to error_diag_len characters

479

of error related diagnosis information is then provided in

480

the buffer error_diagnosis.

481

482

ERRORS

483

The drmaa_get_attribute_names(),

484

drmaa_get_vector_attribute_names(), and

485

drmaa_get_next_attr_name() functions will fail if:

486

487

DRMAA_ERRNO_INTERNAL_ERROR

488

Unexpected or internal DRMAA error, like system call

489

failure, etc.

490

491

DRMAA_ERRNO_DRM_COMMUNICATION_FAILURE

492

Could not contact DRM system for this request.

493

494

DRMAA_ERRNO_AUTH_FAILURE

495

The specified request is not processed successfully due to

496

authorization failure.

497

498

DRMAA_ERRNO_INVALID_ARGUMENT

499

The input value for an argument is invalid.

500

501

DRMAA_ERRNO_NO_ACTIVE_SESSION

502

Failed because there is no active session.

503

504

DRMAA_ERRNO_NO_MEMORY

505

Failed allocating memory.

506

507

The drmaa_get_next_attr_name() will fail if:

508

509

DRMAA_ERRNO_INVALID_ATTRIBUTE_VALUE

510

When there are no more entries in the vector.

511

512