Class: OCI8::LOB

Inherits:
OCIHandle show all
Defined in:
ext/oci8/lob.c,
ext/oci8/lob.c

Overview

This is the abstract base class of large-object data types; BFILE, BLOB, CLOB and NCLOB.

Direct Known Subclasses

BFILE, BLOB, CLOB, NCLOB

Instance Method Summary collapse

Instance Method Details

#available? ⇒ true or false

Returns true when self is initialized.

Returns:

  • (true or false) 


336
337
338
339
340
341
342
343
344
 
# File 'ext/oci8/lob.c', line 336

static VALUE oci8_lob_available_p(VALUE self)
{
    oci8_lob_t *lob = DATA_PTR(self);
    boolean is_initialized;

    chker2(OCILobLocatorIsInit(oci8_envhp, oci8_errhp, lob->base.hp.lob, &is_initialized),
           &lob->base);
    return is_initialized ? Qtrue : Qfalse;
}

#chunk_size ⇒ Integer

Returns the chunk size of a LOB.

Returns:

  • (Integer)

See Also:



666
667
668
669
670
671
672
673
674
675
 
# File 'ext/oci8/lob.c', line 666

static VALUE oci8_lob_get_chunk_size(VALUE self)
{
    oci8_lob_t *lob = DATA_PTR(self);
    oci8_svcctx_t *svcctx = oci8_get_svcctx(lob->svc);
    ub4 len;

    chker2(OCILobGetChunkSize_nb(svcctx, svcctx->base.hp.svc, oci8_errhp, lob->base.hp.lob, &len),
           &svcctx->base);
    return UINT2NUM(len);
}

#close ⇒ self

Closes the lob.

Returns:

  • (self) 


201
202
203
204
205
206
207
 
# File 'ext/oci8/lob.c', line 201

static VALUE oci8_lob_close(VALUE self)
{
    oci8_lob_t *lob = DATA_PTR(self);
    lob_close(lob);
    oci8_base_free(DATA_PTR(self));
    return self;
}

#eof? ⇒ true or false

Returns true if the current offset is at end of lob.

Returns:

  • (true or false) 


376
377
378
379
380
381
382
383
 
# File 'ext/oci8/lob.c', line 376

static VALUE oci8_lob_eof_p(VALUE self)
{
    oci8_lob_t *lob = DATA_PTR(self);
    if (oci8_lob_get_length(lob) < lob->pos)
        return Qfalse;
    else
        return Qtrue;
}

#pos ⇒ Integer Also known as: tell

Returns the current offset. For CLOB and NCLOB it is the number of characters, for BLOB and BFILE it is the number of bytes.

Returns:

  • (Integer) 


365
366
367
368
369
 
# File 'ext/oci8/lob.c', line 365

static VALUE oci8_lob_get_pos(VALUE self)
{
    oci8_lob_t *lob = DATA_PTR(self);
    return UB4_TO_NUM(lob->pos);
}

#read(length = nil) ⇒ String or nil

Reads length characters for CLOB and NCLOB or length bytes for BLOB and BILF from the current position. If length is nil, it reads data until EOF.

It returns a string or nil. nil means it met EOF at beginning. As a special exception, when length is nil and the lob length is zero, it returns an empty string ”.

Parameters:

  • length (Integer)

Returns:



485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
 
# File 'ext/oci8/lob.c', line 485

static VALUE oci8_lob_read(int argc, VALUE *argv, VALUE self)
{
    oci8_lob_t *lob = DATA_PTR(self);
    oci8_svcctx_t *svcctx = oci8_get_svcctx(lob->svc);
    ub4 length;
    ub4 nchar;
    ub4 amt;
    sword rv;
    char buf[8192];
    size_t buf_size_in_char;
    VALUE size;
    VALUE v = rb_ary_new();

    rb_scan_args(argc, argv, "01", &size);
    length = oci8_lob_get_length(lob);
    if (length == 0 && NIL_P(size)) {
        return rb_usascii_str_new("", 0);
    }
    if (length <= lob->pos) /* EOF */
        return Qnil;
    length -= lob->pos;
    if (NIL_P(size)) {
        nchar = length; /* read until EOF */
    } else {
        nchar = NUM2UINT(size);
        if (nchar > length)
            nchar = length;
    }
    amt = nchar;
    buf_size_in_char = sizeof(buf) / lob->char_width;
    do {
        if (lob->state == S_BFILE_CLOSE) {
            rv = OCILobFileOpen_nb(svcctx, svcctx->base.hp.svc, oci8_errhp, lob->base.hp.lob, OCI_FILE_READONLY);
            if (rv == OCI_ERROR && oci8_get_error_code(oci8_errhp) == 22290) {
                /* ORA-22290: operation would exceed the maximum number of opened files or LOBs */
                /* close all opened BFILE implicitly. */
                oci8_base_t *base;
                for (base = &lob->base; base != &lob->base; base = base->next) {
                    if (base->type == OCI_DTYPE_LOB) {
                        oci8_lob_t *tmp = (oci8_lob_t *)base;
                        if (tmp->state == S_BFILE_OPEN) {
                            tmp->state = S_BFILE_CLOSE;
                        }
                    }
                }
                chker2(OCILobFileCloseAll_nb(svcctx, svcctx->base.hp.svc, oci8_errhp),
                       &svcctx->base);
                continue;
            }
            chker2(rv, &svcctx->base);
            lob->state = S_BFILE_OPEN;
        }
        /* initialize buf in zeros everytime to check a nul characters. */
        memset(buf, 0, sizeof(buf));
        rv = OCILobRead_nb(svcctx, svcctx->base.hp.svc, oci8_errhp, lob->base.hp.lob, &amt, lob->pos + 1, buf, sizeof(buf), NULL, NULL, 0, lob->csfrm);
        if (rv == OCI_ERROR && oci8_get_error_code(oci8_errhp) == 22289) {
            /* ORA-22289: cannot perform FILEREAD operation on an unopened file or LOB */
            if (lob->state == S_BFILE_CLOSE)
                continue;
        }
        if (rv != OCI_SUCCESS && rv != OCI_NEED_DATA) {
            chker2(rv, &svcctx->base);
        }

        /* Workaround when using Oracle 10.2.0.4 or 11.1.0.6 client and
         * variable-length character set (e.g. AL32UTF8).
         *
         * When the above mentioned condition, amt may be shorter. So
         * amt is increaded until a nul character to know the actually
         * read size.
         */
        while (amt < sizeof(buf) && buf[amt] != '\0') {
            amt++;
        }

        if (amt == 0)
            break;
        /* for fixed size charset, amt is the number of characters stored in buf. */
        if (amt > buf_size_in_char)
            rb_raise(eOCIException, "Too large buffer fetched or you set too large size of a character.");
        amt *= lob->char_width;
        rb_ary_push(v, rb_str_new(buf, amt));
    } while (rv == OCI_NEED_DATA);
    lob->pos += nchar;
    if (nchar == length) {
        lob_close(lob);
        bfile_close(lob);
    }
    if (RARRAY_LEN(v) == 0) {
        return Qnil;
    }
    v = rb_ary_join(v, Qnil);
    OBJ_TAINT(v);
    if (lob->lobtype == OCI_TEMP_CLOB) {
        /* set encoding */
        rb_enc_associate(v, oci8_encoding);
        return rb_str_conv_enc(v, oci8_encoding, rb_default_internal_encoding());
    } else {
        /* ASCII-8BIT */
        return v;
    }
}

#rewind ⇒ true or false

Sets the current offset at the beginning.

Returns:

  • (true or false) 


428
429
430
431
432
433
 
# File 'ext/oci8/lob.c', line 428

static VALUE oci8_lob_rewind(VALUE self)
{
    oci8_lob_t *lob = DATA_PTR(self);
    lob->pos = 0;
    return self;
}

#seek(amount, whence = IO::SEEK_SET) ⇒ self

Seeks to the given offset in the stream. The new position, measured in characters, is obtained by adding offset amount to the position specified by whence. If whence is set to IO::SEEK_SET, IO::SEEK_CUR, or IO::SEEK_END, the offset is relative to the start of the file, the current position indicator, or end-of-file, respectively.

Parameters:

  • amount (Integer)
  • whence (IO::SEEK_SET, IO::SEEK_CUR or IO::SEEK_END)

Returns:

  • (self) 


399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
 
# File 'ext/oci8/lob.c', line 399

static VALUE oci8_lob_seek(int argc, VALUE *argv, VALUE self)
{
    oci8_lob_t *lob = DATA_PTR(self);
    VALUE position, whence;

    rb_scan_args(argc, argv, "11", &position, &whence);
    if (argc == 2 && (whence != seek_set && whence != seek_cur && whence != seek_end)) {
        if (FIXNUM_P(whence)) {
            rb_raise(rb_eArgError, "expect IO::SEEK_SET, IO::SEEK_CUR or IO::SEEK_END but %d",
                     FIX2INT(whence));
        } else {
            rb_raise(rb_eArgError, "expect IO::SEEK_SET, IO::SEEK_CUR or IO::SEEK_END but %s",
                     rb_class2name(CLASS_OF(whence)));
        }
    }
    if (whence == seek_cur) {
        position = rb_funcall(UB4_TO_NUM(lob->pos), id_plus, 1, position);
    } else if (whence == seek_end) {
        position = rb_funcall(UB4_TO_NUM(oci8_lob_get_length(lob)), id_plus, 1, position);
    }
    lob->pos = NUM2UINT(position);
    return self;
}

#size ⇒ Integer

Returns the size. For CLOB and NCLOB it is the number of characters, for BLOB and BFILE it is the number of bytes.

Returns:

  • (Integer) 


353
354
355
356
 
# File 'ext/oci8/lob.c', line 353

static VALUE oci8_lob_get_size(VALUE self)
{
    return UB4_TO_NUM(oci8_lob_get_length(DATA_PTR(self)));
}

#size=(length) ⇒ Integer

Changes the lob size to the given length.

Parameters:

  • length (Integer)

Returns:

  • (Integer) 


464
465
466
467
468
 
# File 'ext/oci8/lob.c', line 464

static VALUE oci8_lob_set_size(VALUE self, VALUE len)
{
    oci8_lob_truncate(self, len);
    return len;
}

#truncate(length) ⇒ self

Changes the lob size to the given length.

Parameters:

  • length (Integer)

Returns:

  • (self) 


444
445
446
447
448
449
450
451
452
453
 
# File 'ext/oci8/lob.c', line 444

static VALUE oci8_lob_truncate(VALUE self, VALUE len)
{
    oci8_lob_t *lob = DATA_PTR(self);
    oci8_svcctx_t *svcctx = oci8_get_svcctx(lob->svc);

    lob_open(lob);
    chker2(OCILobTrim_nb(svcctx, svcctx->base.hp.svc, oci8_errhp, lob->base.hp.lob, NUM2UINT(len)),
           &svcctx->base);
    return self;
}

#write(data) ⇒ Integer

Writes data.

Parameters:

Returns:

  • (Integer) 


597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
 
# File 'ext/oci8/lob.c', line 597

static VALUE oci8_lob_write(VALUE self, VALUE data)
{
    oci8_lob_t *lob = DATA_PTR(self);
    oci8_svcctx_t *svcctx = oci8_get_svcctx(lob->svc);
    ub4 amt;

    lob_open(lob);
    if (TYPE(data) != T_STRING) {
        data = rb_obj_as_string(data);
    }
    if (lob->lobtype == OCI_TEMP_CLOB) {
        data = rb_str_export_to_enc(data, oci8_encoding);
    }
    RB_GC_GUARD(data);
    amt = RSTRING_LEN(data);
    if (amt == 0) {
        /* to avoid ORA-24801: illegal parameter value in OCI lob function */
        return INT2FIX(0);
    }
    chker2(OCILobWrite_nb(svcctx, svcctx->base.hp.svc, oci8_errhp, lob->base.hp.lob, &amt, lob->pos + 1, RSTRING_PTR(data), amt, OCI_ONE_PIECE, NULL, NULL, 0, lob->csfrm),
           &svcctx->base);
    lob->pos += amt;
    return UINT2NUM(amt);
}