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) 


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

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:



707
708
709
710
711
712
713
714
715
716
 
# File 'ext/oci8/lob.c', line 707

static VALUE oci8_lob_get_chunk_size(VALUE self)
{
    oci8_lob_t *lob = DATA_PTR(self);
    oci8_svcctx_t *svcctx = check_svcctx(lob);
    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) 


232
233
234
235
236
237
238
 
# File 'ext/oci8/lob.c', line 232

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) 


405
406
407
408
409
410
411
412
 
# File 'ext/oci8/lob.c', line 405

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) 


394
395
396
397
398
 
# File 'ext/oci8/lob.c', line 394

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:



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
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
 
# File 'ext/oci8/lob.c', line 514

static VALUE oci8_lob_read(int argc, VALUE *argv, VALUE self)
{
    oci8_lob_t *lob = DATA_PTR(self);
    oci8_svcctx_t *svcctx = check_svcctx(lob);
    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);
        svcctx->suppress_free_temp_lobs = 0;
        switch (rv) {
        case OCI_SUCCESS:
            break;
        case OCI_NEED_DATA:
            /* prevent OCILobFreeTemporary() from being called.
             * See: https://github.com/kubo/ruby-oci8/issues/20
             */
            svcctx->suppress_free_temp_lobs = 1;
            break;
        case OCI_ERROR:
            if (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;
            }
            /* FALLTHROUGH */
        default:
            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) 


457
458
459
460
461
462
 
# File 'ext/oci8/lob.c', line 457

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) 


428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
 
# File 'ext/oci8/lob.c', line 428

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) 


382
383
384
385
 
# File 'ext/oci8/lob.c', line 382

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) 


493
494
495
496
497
 
# File 'ext/oci8/lob.c', line 493

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) 


473
474
475
476
477
478
479
480
481
482
 
# File 'ext/oci8/lob.c', line 473

static VALUE oci8_lob_truncate(VALUE self, VALUE len)
{
    oci8_lob_t *lob = DATA_PTR(self);
    oci8_svcctx_t *svcctx = check_svcctx(lob);

    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) 


638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
 
# File 'ext/oci8/lob.c', line 638

static VALUE oci8_lob_write(VALUE self, VALUE data)
{
    oci8_lob_t *lob = DATA_PTR(self);
    oci8_svcctx_t *svcctx = check_svcctx(lob);
    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);
}